From 001aa8a82a9b5209412500ccdb74dcbca5d93984 Mon Sep 17 00:00:00 2001 From: Azure SDK for Python bot Date: Wed, 1 May 2019 13:58:04 -0700 Subject: [PATCH 1/4] [AutoPR cognitiveservices/data-plane/FormRecognizer] Cognitive Services Form Recognizer - Initial commit. (#3494) * Generated from 29e2bc765c43c5181003c994c191e81a87be5bb9 Updated return type for /models api * Generated from 8385975148ed0e78dcb8126d1a8ceaf602139d2e removing multi as it causing autorest codegen issues with langs like go, ruby etc. * Generated from afc041b90293c894a3ff3ec8f08cd52dbec4d6e7 API review feedback, Reverting OpIds --- .../vision/faceapi/FaceClient.java | 146 ++ .../vision/faceapi/FaceLists.java | 909 +++++--- .../vision/faceapi/Faces.java | 1063 +++++---- .../vision/faceapi/LargeFaceLists.java | 1139 +++++++++ .../faceapi/LargePersonGroupPersons.java | 823 +++++++ .../vision/faceapi/LargePersonGroups.java | 618 +++++ .../vision/faceapi/PersonGroupPersons.java | 1234 +++++----- .../vision/faceapi/PersonGroups.java | 645 ++++-- .../vision/faceapi/Snapshots.java | 610 +++++ .../implementation/FaceClientImpl.java | 290 +++ .../faceapi/implementation/FaceListsImpl.java | 1012 +++++--- .../faceapi/implementation/FacesImpl.java | 1163 ++++++---- .../implementation/LargeFaceListsImpl.java | 2050 +++++++++++++++++ .../LargePersonGroupPersonsImpl.java | 1579 +++++++++++++ .../implementation/LargePersonGroupsImpl.java | 1099 +++++++++ .../PersonGroupPersonsImpl.java | 1216 +++++----- .../implementation/PersonGroupsImpl.java | 773 ++++--- .../faceapi/implementation/SnapshotsImpl.java | 1122 +++++++++ .../faceapi/implementation/package-info.java | 2 +- .../vision/faceapi/models/Accessory.java | 8 +- .../faceapi/models/ApplySnapshotRequest.java | 73 + .../vision/faceapi/models/Blur.java | 8 +- .../vision/faceapi/models/Coordinate.java | 8 +- .../vision/faceapi/models/DetectedFace.java | 26 + .../vision/faceapi/models/Exposure.java | 8 +- .../vision/faceapi/models/FaceAttributes.java | 59 +- .../vision/faceapi/models/FaceList.java | 10 +- .../vision/faceapi/models/FaceRectangle.java | 16 +- .../faceapi/models/FindSimilarRequest.java | 58 +- .../vision/faceapi/models/Gender.java | 5 +- .../vision/faceapi/models/GroupRequest.java | 4 +- .../vision/faceapi/models/GroupResult.java | 8 +- .../vision/faceapi/models/Hair.java | 12 +- .../vision/faceapi/models/HairColor.java | 8 +- .../faceapi/models/IdentifyCandidate.java | 8 +- .../faceapi/models/IdentifyRequest.java | 71 +- .../vision/faceapi/models/IdentifyResult.java | 8 +- .../vision/faceapi/models/ImageUrl.java | 4 +- .../vision/faceapi/models/LargeFaceList.java | 43 + .../faceapi/models/LargePersonGroup.java | 43 + .../vision/faceapi/models/Makeup.java | 8 +- .../faceapi/models/MetaDataContract.java | 44 + .../models/NameAndUserDataContract.java | 10 +- .../vision/faceapi/models/Noise.java | 8 +- .../vision/faceapi/models/Occlusion.java | 12 +- .../faceapi/models/OperationStatus.java | 169 ++ .../faceapi/models/OperationStatusType.java | 59 + .../vision/faceapi/models/PersistedFace.java | 8 +- .../vision/faceapi/models/Person.java | 8 +- .../vision/faceapi/models/PersonGroup.java | 8 +- .../faceapi/models/RecognitionModel.java | 41 + .../vision/faceapi/models/SimilarFace.java | 12 +- .../vision/faceapi/models/Snapshot.java | 214 ++ .../faceapi/models/SnapshotApplyHeaders.java | 44 + .../faceapi/models/SnapshotApplyMode.java | 50 + .../faceapi/models/SnapshotObjectType.java | 59 + .../faceapi/models/SnapshotTakeHeaders.java | 46 + .../faceapi/models/TakeSnapshotRequest.java | 129 ++ .../vision/faceapi/models/TrainingStatus.java | 61 +- .../faceapi/models/UpdateFaceRequest.java | 43 + .../faceapi/models/UpdateSnapshotRequest.java | 76 + .../models/VerifyFaceToFaceRequest.java | 10 +- .../models/VerifyFaceToPersonRequest.java | 56 +- .../vision/faceapi/models/VerifyResult.java | 8 +- .../vision/faceapi/models/package-info.java | 2 +- .../vision/faceapi/package-info.java | 2 +- ...tiveServiceFormRecognizerAPIV1Preview.java | 430 ++++ ...ServiceFormRecognizerAPIV1PreviewImpl.java | 829 +++++++ .../implementation/package-info.java | 11 + .../formrecognizer/models/AnalyzeResult.java | 103 + .../models/ErrorInformation.java | 95 + .../formrecognizer/models/ErrorResponse.java | 43 + .../models/ErrorResponseException.java | 44 + .../models/ExtractedKeyValuePair.java | 71 + .../formrecognizer/models/ExtractedPage.java | 175 ++ .../formrecognizer/models/ExtractedTable.java | 71 + .../models/ExtractedTableColumn.java | 74 + .../formrecognizer/models/ExtractedToken.java | 108 + .../models/FormDocumentReport.java | 123 + .../models/FormOperationError.java | 43 + .../formrecognizer/models/InnerError.java | 43 + .../formrecognizer/models/KeysResult.java | 46 + .../formrecognizer/models/ModelResult.java | 124 + .../formrecognizer/models/ModelsResult.java | 44 + .../formrecognizer/models/TrainRequest.java | 43 + .../formrecognizer/models/TrainResult.java | 100 + .../formrecognizer/models/package-info.java | 11 + .../formrecognizer/package-info.java | 11 + 88 files changed, 18408 insertions(+), 3402 deletions(-) create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceClient.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargeFaceLists.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroupPersons.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroups.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Snapshots.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceClientImpl.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargeFaceListsImpl.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupPersonsImpl.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupsImpl.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/SnapshotsImpl.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ApplySnapshotRequest.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargeFaceList.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargePersonGroup.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/MetaDataContract.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatus.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatusType.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/RecognitionModel.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Snapshot.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyHeaders.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyMode.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotObjectType.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotTakeHeaders.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TakeSnapshotRequest.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateFaceRequest.java create mode 100644 cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateSnapshotRequest.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/CognitiveServiceFormRecognizerAPIV1Preview.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/CognitiveServiceFormRecognizerAPIV1PreviewImpl.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/AnalyzeResult.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorInformation.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponse.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponseException.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedKeyValuePair.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedPage.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTable.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTableColumn.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedToken.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormDocumentReport.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormOperationError.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/InnerError.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/KeysResult.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelResult.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelsResult.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainRequest.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainResult.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceClient.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceClient.java new file mode 100644 index 000000000000..a18a89765200 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceClient.java @@ -0,0 +1,146 @@ +/** + * 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.AzureClient; +import com.microsoft.rest.RestClient; + +/** + * The interface for FaceClient class. + */ +public interface FaceClient { + /** + * Gets the REST client. + * + * @return the {@link RestClient} object. + */ + RestClient restClient(); + + /** + * Gets the {@link AzureClient} used for long running operations. + * @return the azure client; + */ + AzureClient getAzureClient(); + + /** + * Gets the User-Agent header for the client. + * + * @return the user agent string. + */ + String userAgent(); + + /** + * Gets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).. + * + * @return the endpoint value. + */ + String endpoint(); + + /** + * Sets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).. + * + * @param endpoint the endpoint value. + * @return the service client itself + */ + FaceClient withEndpoint(String endpoint); + + /** + * Gets The preferred language for the response.. + * + * @return the acceptLanguage value. + */ + String acceptLanguage(); + + /** + * Sets The preferred language for the response.. + * + * @param acceptLanguage the acceptLanguage value. + * @return the service client itself + */ + FaceClient withAcceptLanguage(String acceptLanguage); + + /** + * Gets The retry timeout in seconds for Long Running Operations. Default value is 30.. + * + * @return the longRunningOperationRetryTimeout value. + */ + int longRunningOperationRetryTimeout(); + + /** + * Sets The retry timeout in seconds for Long Running Operations. Default value is 30.. + * + * @param longRunningOperationRetryTimeout the longRunningOperationRetryTimeout value. + * @return the service client itself + */ + FaceClient withLongRunningOperationRetryTimeout(int longRunningOperationRetryTimeout); + + /** + * Gets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true.. + * + * @return the generateClientRequestId value. + */ + boolean generateClientRequestId(); + + /** + * Sets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true.. + * + * @param generateClientRequestId the generateClientRequestId value. + * @return the service client itself + */ + FaceClient withGenerateClientRequestId(boolean generateClientRequestId); + + /** + * Gets the Faces object to access its operations. + * @return the Faces object. + */ + Faces faces(); + + /** + * Gets the PersonGroupPersons object to access its operations. + * @return the PersonGroupPersons object. + */ + PersonGroupPersons personGroupPersons(); + + /** + * Gets the PersonGroups object to access its operations. + * @return the PersonGroups object. + */ + PersonGroups personGroups(); + + /** + * Gets the FaceLists object to access its operations. + * @return the FaceLists object. + */ + FaceLists faceLists(); + + /** + * Gets the LargePersonGroupPersons object to access its operations. + * @return the LargePersonGroupPersons object. + */ + LargePersonGroupPersons largePersonGroupPersons(); + + /** + * Gets the LargePersonGroups object to access its operations. + * @return the LargePersonGroups object. + */ + LargePersonGroups largePersonGroups(); + + /** + * Gets the LargeFaceLists object to access its operations. + * @return the LargeFaceLists object. + */ + LargeFaceLists largeFaceLists(); + + /** + * Gets the Snapshots object to access its operations. + * @return the Snapshots object. + */ + Snapshots snapshots(); + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceLists.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceLists.java index 4c81ca14a130..f425ff7ab434 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceLists.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/FaceLists.java @@ -8,13 +8,14 @@ package com.microsoft.azure.cognitiveservices.vision.faceapi; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.CreateFaceListsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateFaceListsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddFaceFromUrlOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddFaceFromStreamOptionalParameter; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.FaceList; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; import java.util.List; import java.util.UUID; import rx.Observable; @@ -25,217 +26,314 @@ */ public interface FaceLists { /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * * @param faceListId Id referencing a particular face list. - * @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 faceListId, CreateFaceListsOptionalParameter createOptionalParameter); + void create(String faceListId); /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * * @param faceListId Id referencing a particular face list. - * @param createOptionalParameter the object representing the optional parameters to be set before calling this API + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - - Observable createAsync(String faceListId, CreateFaceListsOptionalParameter createOptionalParameter); + ServiceFuture createAsync(String faceListId, final ServiceCallback serviceCallback); /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * - * @return the first stage of the create call + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - FaceListsCreateDefinitionStages.WithFaceListId create(); + Observable createAsync(String faceListId); /** - * Grouping of create definition stages. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - interface FaceListsCreateDefinitionStages { - /** - * The stage of the definition to be specify faceListId. - */ - interface WithFaceListId { - /** - * Id referencing a particular face list. - * - * @return next definition stage - */ - FaceListsCreateDefinitionStages.WithExecute withFaceListId(String faceListId); - } - - /** - * 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 - */ - FaceListsCreateDefinitionStages.WithExecute withName(String name); + Observable> createWithServiceResponseAsync(String faceListId); + /** + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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 faceListId, String name, String userData, RecognitionModel recognitionModel); - /** - * User specified data. Length should not exceed 16KB. - * - * @return next definition stage - */ - FaceListsCreateDefinitionStages.WithExecute withUserData(String userData); + /** + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String faceListId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback); - } + /** + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable createAsync(String faceListId, String name, String userData, RecognitionModel recognitionModel); - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FaceListsCreateDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - */ - void execute(); + /** + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> createWithServiceResponseAsync(String faceListId, String name, String userData, RecognitionModel recognitionModel); - /** - * Execute the request asynchronously. - * - * @return a representation of the deferred computation of this call if successful. - */ - Observable executeAsync(); - } - } + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @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 FaceList object if successful. + */ + FaceList get(String faceListId); /** - * The entirety of create definition. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object */ - interface FaceListsCreateDefinition extends - FaceListsCreateDefinitionStages.WithFaceListId, - FaceListsCreateDefinitionStages.WithExecute { - } + ServiceFuture getAsync(String faceListId, final ServiceCallback serviceCallback); + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the FaceList object + */ + Observable getAsync(String faceListId); /** - * Retrieve a face list's information. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. * * @param faceListId Id referencing a particular face list. * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the FaceList object + */ + Observable> getWithServiceResponseAsync(String faceListId); + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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 FaceList object if successful. */ - FaceList get(String faceListId); + FaceList get(String faceListId, Boolean returnRecognitionModel); /** - * Retrieve a face list's information. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. * * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String faceListId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback); + + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the FaceList object */ - Observable getAsync(String faceListId); + Observable getAsync(String faceListId, Boolean returnRecognitionModel); + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the FaceList object + */ + Observable> getWithServiceResponseAsync(String faceListId, Boolean returnRecognitionModel); /** * Update information of a face list. * * @param faceListId Id referencing a particular face list. - * @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 faceListId, UpdateFaceListsOptionalParameter updateOptionalParameter); + void update(String faceListId); /** * Update information of a face list. * * @param faceListId Id referencing a particular face list. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - - Observable updateAsync(String faceListId, UpdateFaceListsOptionalParameter updateOptionalParameter); + ServiceFuture updateAsync(String faceListId, final ServiceCallback serviceCallback); /** * Update information of a face list. * - * @return the first stage of the update call + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - FaceListsUpdateDefinitionStages.WithFaceListId update(); + Observable updateAsync(String faceListId); /** - * Grouping of update definition stages. + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - interface FaceListsUpdateDefinitionStages { - /** - * The stage of the definition to be specify faceListId. - */ - interface WithFaceListId { - /** - * Id referencing a particular face list. - * - * @return next definition stage - */ - FaceListsUpdateDefinitionStages.WithExecute withFaceListId(String faceListId); - } - - /** - * 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 - */ - FaceListsUpdateDefinitionStages.WithExecute withName(String name); - - /** - * User specified data. Length should not exceed 16KB. - * - * @return next definition stage - */ - FaceListsUpdateDefinitionStages.WithExecute withUserData(String userData); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FaceListsUpdateDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - */ - void execute(); + Observable> updateWithServiceResponseAsync(String faceListId); + /** + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 faceListId, String name, String userData); - /** - * Execute the request asynchronously. - * - * @return a representation of the deferred computation of this call if successful. - */ - Observable executeAsync(); - } - } + /** + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String faceListId, String name, String userData, final ServiceCallback serviceCallback); /** - * The entirety of update definition. + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - interface FaceListsUpdateDefinition extends - FaceListsUpdateDefinitionStages.WithFaceListId, - FaceListsUpdateDefinitionStages.WithExecute { - } + Observable updateAsync(String faceListId, String name, String userData); + /** + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String faceListId, String name, String userData); /** - * Delete an existing face list according to faceListId. Persisted face images in the face list will - * also be deleted. + * Delete a specified face list. * * @param faceListId Id referencing a particular face list. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -245,20 +343,36 @@ interface FaceListsUpdateDefinition extends void delete(String faceListId); /** - * Delete an existing face list according to faceListId. Persisted face images in the face list will - * also be deleted. + * Delete a specified face list. * * @param faceListId Id referencing a particular face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - Observable deleteAsync(String faceListId); + ServiceFuture deleteAsync(String faceListId, final ServiceCallback serviceCallback); + /** + * Delete a specified face list. + * + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteAsync(String faceListId); + /** + * Delete a specified face list. + * + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteWithServiceResponseAsync(String faceListId); /** - * Retrieve information about all existing face lists. Only faceListId, name and userData will be - * returned. + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). * * @throws IllegalArgumentException thrown if parameters fail the validation * @throws APIErrorException thrown if the request is rejected by server @@ -268,19 +382,78 @@ interface FaceListsUpdateDefinition extends List list(); /** - * Retrieve information about all existing face lists. Only faceListId, name and userData will be - * returned. + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(final ServiceCallback> serviceCallback); + + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). * * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<FaceList> object */ Observable> listAsync(); + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<FaceList> object + */ + Observable>> listWithServiceResponseAsync(); + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<FaceList> object if successful. + */ + List list(Boolean returnRecognitionModel); + + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(Boolean returnRecognitionModel, final ServiceCallback> serviceCallback); + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<FaceList> object + */ + Observable> listAsync(Boolean returnRecognitionModel); /** - * Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). Persisted - * image related to the face will also be deleted. + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<FaceList> object + */ + Observable>> listWithServiceResponseAsync(Boolean returnRecognitionModel); + + /** + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. @@ -291,245 +464,279 @@ interface FaceListsUpdateDefinition extends void deleteFace(String faceListId, UUID persistedFaceId); /** - * Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). Persisted - * image related to the face will also be deleted. + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteFaceAsync(String faceListId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ Observable deleteFaceAsync(String faceListId, UUID persistedFaceId); + /** + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteFaceWithServiceResponseAsync(String faceListId, UUID persistedFaceId); + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromUrl(String faceListId, String url); + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String faceListId, String url, final ServiceCallback serviceCallback); + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromUrlAsync(String faceListId, String url); + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String faceListId, String url); + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromUrl(String faceListId, String url, String userData, List targetFace); + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String faceListId, String url, String userData, List targetFace, final ServiceCallback serviceCallback); /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a - * persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. - * @param url Publicly reachable URL of an image. - * @param addFaceFromUrlOptionalParameter the object representing the optional parameters to be set before calling this API + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromUrlAsync(String faceListId, String url, String userData, List targetFace); + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String faceListId, String url, String userData, List targetFace); + + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. * @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 PersistedFace object if successful. */ - - PersistedFace addFaceFromUrl(String faceListId, String url, AddFaceFromUrlOptionalParameter addFaceFromUrlOptionalParameter); + PersistedFace addFaceFromStream(String faceListId, byte[] image); + + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String faceListId, byte[] image, final ServiceCallback serviceCallback); + + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String faceListId, byte[] image); /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a - * persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. * * @param faceListId Id referencing a particular face list. - * @param url Publicly reachable URL of an image. - * @param addFaceFromUrlOptionalParameter the object representing the optional parameters to be set before calling this API + * @param image An image stream. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the PersistedFace object */ - - Observable addFaceFromUrlAsync(String faceListId, String url, AddFaceFromUrlOptionalParameter addFaceFromUrlOptionalParameter); - - /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a - * persistedFaceId representing the added face, and persistedFaceId will not expire. - * - * @return the first stage of the addFaceFromUrl call - */ - FaceListsAddFaceFromUrlDefinitionStages.WithFaceListId addFaceFromUrl(); - - /** - * Grouping of addFaceFromUrl definition stages. - */ - interface FaceListsAddFaceFromUrlDefinitionStages { - /** - * The stage of the definition to be specify faceListId. - */ - interface WithFaceListId { - /** - * Id referencing a particular face list. - * - * @return next definition stage - */ - WithUrl withFaceListId(String faceListId); - } - /** - * The stage of the definition to be specify url. - */ - interface WithUrl { - /** - * Publicly reachable URL of an image. - * - * @return next definition stage - */ - FaceListsAddFaceFromUrlDefinitionStages.WithExecute withUrl(String url); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * User-specified data about the face for any purpose. The maximum length is 1KB. - * - * @return next definition stage - */ - FaceListsAddFaceFromUrlDefinitionStages.WithExecute withUserData(String userData); - - /** - * A face rectangle to specify the target face to be added to a person in the format of - * "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the - * image, targetFace is required to specify which face to add. No targetFace means there is only one face - * detected in the entire image. - * - * @return next definition stage - */ - FaceListsAddFaceFromUrlDefinitionStages.WithExecute withTargetFace(List targetFace); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FaceListsAddFaceFromUrlDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the PersistedFace object if successful. - */ - PersistedFace execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the PersistedFace object - */ - Observable executeAsync(); - } - } - - /** - * The entirety of addFaceFromUrl definition. - */ - interface FaceListsAddFaceFromUrlDefinition extends - FaceListsAddFaceFromUrlDefinitionStages.WithFaceListId, - FaceListsAddFaceFromUrlDefinitionStages.WithUrl, - FaceListsAddFaceFromUrlDefinitionStages.WithExecute { - } - - /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a - * persistedFaceId representing the added face, and persistedFaceId will not expire. + Observable> addFaceFromStreamWithServiceResponseAsync(String faceListId, byte[] image); + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. * * @param faceListId Id referencing a particular face list. * @param image An image stream. - * @param addFaceFromStreamOptionalParameter the object representing the optional parameters to be set before calling this API + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. * @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 PersistedFace object if successful. */ - - PersistedFace addFaceFromStream(String faceListId, byte[] image, AddFaceFromStreamOptionalParameter addFaceFromStreamOptionalParameter); + PersistedFace addFaceFromStream(String faceListId, byte[] image, String userData, List targetFace); + + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String faceListId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback); + + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String faceListId, byte[] image, String userData, List targetFace); /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a - * persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. * * @param faceListId Id referencing a particular face list. * @param image An image stream. - * @param addFaceFromStreamOptionalParameter the object representing the optional parameters to be set before calling this API + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the PersistedFace object */ - - Observable addFaceFromStreamAsync(String faceListId, byte[] image, AddFaceFromStreamOptionalParameter addFaceFromStreamOptionalParameter); - - /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a - * persistedFaceId representing the added face, and persistedFaceId will not expire. - * - * @return the first stage of the addFaceFromStream call - */ - FaceListsAddFaceFromStreamDefinitionStages.WithFaceListId addFaceFromStream(); - - /** - * Grouping of addFaceFromStream definition stages. - */ - interface FaceListsAddFaceFromStreamDefinitionStages { - /** - * The stage of the definition to be specify faceListId. - */ - interface WithFaceListId { - /** - * Id referencing a particular face list. - * - * @return next definition stage - */ - WithImage withFaceListId(String faceListId); - } - /** - * The stage of the definition to be specify image. - */ - interface WithImage { - /** - * An image stream. - * - * @return next definition stage - */ - FaceListsAddFaceFromStreamDefinitionStages.WithExecute withImage(byte[] image); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * User-specified data about the face for any purpose. The maximum length is 1KB. - * - * @return next definition stage - */ - FaceListsAddFaceFromStreamDefinitionStages.WithExecute withUserData(String userData); - - /** - * A face rectangle to specify the target face to be added to a person in the format of - * "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the - * image, targetFace is required to specify which face to add. No targetFace means there is only one face - * detected in the entire image. - * - * @return next definition stage - */ - FaceListsAddFaceFromStreamDefinitionStages.WithExecute withTargetFace(List targetFace); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FaceListsAddFaceFromStreamDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the PersistedFace object if successful. - */ - PersistedFace execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the PersistedFace object - */ - Observable executeAsync(); - } - } - - /** - * The entirety of addFaceFromStream definition. - */ - interface FaceListsAddFaceFromStreamDefinition extends - FaceListsAddFaceFromStreamDefinitionStages.WithFaceListId, - FaceListsAddFaceFromStreamDefinitionStages.WithImage, - FaceListsAddFaceFromStreamDefinitionStages.WithExecute { - } + Observable> addFaceFromStreamWithServiceResponseAsync(String faceListId, byte[] image, String userData, List targetFace); } diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Faces.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Faces.java index 99629847497d..f63c934ebde9 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Faces.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Faces.java @@ -8,18 +8,19 @@ package com.microsoft.azure.cognitiveservices.vision.faceapi; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.FindSimilarOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.IdentifyOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.DetectWithUrlOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.DetectWithStreamOptionalParameter; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.DetectedFace; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.FaceAttributeType; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.FindSimilarMatchMode; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.GroupResult; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.IdentifyResult; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SimilarFace; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.VerifyResult; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; import java.util.List; import java.util.UUID; import rx.Observable; @@ -30,126 +31,126 @@ */ public interface Faces { /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. * - * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this - * faceId is not persisted and will expire 24 hours after the detection call. - * @param findSimilarOptionalParameter the object representing the optional parameters to be set before calling this API + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call * @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<SimilarFace> object if successful. */ - - List findSimilar(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter); + List findSimilar(UUID faceId); /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. * - * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this - * faceId is not persisted and will expire 24 hours after the detection call. - * @param findSimilarOptionalParameter the object representing the optional parameters to be set before calling this API + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> findSimilarAsync(UUID faceId, final ServiceCallback> serviceCallback); + + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<SimilarFace> object + */ + Observable> findSimilarAsync(UUID faceId); + + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<SimilarFace> object */ - - Observable> findSimilarAsync(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter); - - /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. - * - * @return the first stage of the findSimilar call - */ - FacesFindSimilarDefinitionStages.WithFaceId findSimilar(); - - /** - * Grouping of findSimilar definition stages. - */ - interface FacesFindSimilarDefinitionStages { - /** - * The stage of the definition to be specify faceId. - */ - interface WithFaceId { - /** - * FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this - * faceId is not persisted and will expire 24 hours after the detection call. - * - * @return next definition stage - */ - FacesFindSimilarDefinitionStages.WithExecute withFaceId(UUID faceId); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list - * contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId and - * faceIds should not be provided at the same time. - * - * @return next definition stage - */ - FacesFindSimilarDefinitionStages.WithExecute withFaceListId(String faceListId); - - /** - * An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours - * after the detection call. - * - * @return next definition stage - */ - FacesFindSimilarDefinitionStages.WithExecute withFaceIds(List faceIds); - - /** - * The number of top similar faces returned. The valid range is [1, 1000]. - * - * @return next definition stage - */ - FacesFindSimilarDefinitionStages.WithExecute withMaxNumOfCandidatesReturned(Integer maxNumOfCandidatesReturned); - - /** - * Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', - * 'matchFace'. - * - * @return next definition stage - */ - FacesFindSimilarDefinitionStages.WithExecute withMode(FindSimilarMatchMode mode); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FacesFindSimilarDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the List<SimilarFace> object if successful. - */ - List execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the List<SimilarFace> object - */ - Observable> executeAsync(); - } - } - - /** - * The entirety of findSimilar definition. - */ - interface FacesFindSimilarDefinition extends - FacesFindSimilarDefinitionStages.WithFaceId, - FacesFindSimilarDefinitionStages.WithExecute { - } - - - /** - * Divide candidate faces into groups based on face similarity. - * - * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces. + Observable>> findSimilarWithServiceResponseAsync(UUID faceId); + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. + * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' + * @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<SimilarFace> object if successful. + */ + List findSimilar(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode); + + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. + * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> findSimilarAsync(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode, final ServiceCallback> serviceCallback); + + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. + * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<SimilarFace> object + */ + Observable> findSimilarAsync(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode); + + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. + * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<SimilarFace> object + */ + Observable>> findSimilarWithServiceResponseAsync(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode); + + /** + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. + * + * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces * @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 @@ -158,134 +159,220 @@ interface FacesFindSimilarDefinition extends GroupResult group(List faceIds); /** - * Divide candidate faces into groups based on face similarity. + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. + * + * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture groupAsync(List faceIds, final ServiceCallback serviceCallback); + + /** + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. * - * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces. + * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the GroupResult object */ Observable groupAsync(List faceIds); + /** + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. + * + * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the GroupResult object + */ + Observable> groupWithServiceResponseAsync(List faceIds); /** - * Identify unknown faces from a person group. + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. * - * @param personGroupId PersonGroupId of the target person group, created by PersonGroups.Create. - * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. - * The valid number of faceIds is between [1, 10]. - * @param identifyOptionalParameter the object representing the optional parameters to be set before calling this API + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. * @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<IdentifyResult> object if successful. */ - - List identify(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter); + List identify(List faceIds); + + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> identifyAsync(List faceIds, final ServiceCallback> serviceCallback); /** - * Identify unknown faces from a person group. + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. * - * @param personGroupId PersonGroupId of the target person group, created by PersonGroups.Create. - * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. - * The valid number of faceIds is between [1, 10]. - * @param identifyOptionalParameter the object representing the optional parameters to be set before calling this API + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<IdentifyResult> object */ - - Observable> identifyAsync(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter); - - /** - * Identify unknown faces from a person group. - * - * @return the first stage of the identify call - */ - FacesIdentifyDefinitionStages.WithPersonGroupId identify(); - - /** - * Grouping of identify definition stages. - */ - interface FacesIdentifyDefinitionStages { - /** - * The stage of the definition to be specify personGroupId. - */ - interface WithPersonGroupId { - /** - * PersonGroupId of the target person group, created by PersonGroups.Create. - * - * @return next definition stage - */ - WithFaceIds withPersonGroupId(String personGroupId); - } - /** - * The stage of the definition to be specify faceIds. - */ - interface WithFaceIds { - /** - * Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. - * The valid number of faceIds is between [1, 10]. - * - * @return next definition stage - */ - FacesIdentifyDefinitionStages.WithExecute withFaceIds(List faceIds); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). - * - * @return next definition stage - */ - FacesIdentifyDefinitionStages.WithExecute withMaxNumOfCandidatesReturned(Integer maxNumOfCandidatesReturned); - - /** - * Confidence threshold of identification, used to judge whether one face belong to one person. The range of - * confidenceThreshold is [0, 1] (default specified by algorithm). - * - * @return next definition stage - */ - FacesIdentifyDefinitionStages.WithExecute withConfidenceThreshold(Double confidenceThreshold); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FacesIdentifyDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the List<IdentifyResult> object if successful. - */ - List execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the List<IdentifyResult> object - */ - Observable> executeAsync(); - } - } - - /** - * The entirety of identify definition. - */ - interface FacesIdentifyDefinition extends - FacesIdentifyDefinitionStages.WithPersonGroupId, - FacesIdentifyDefinitionStages.WithFaceIds, - FacesIdentifyDefinitionStages.WithExecute { - } + Observable> identifyAsync(List faceIds); + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<IdentifyResult> object + */ + Observable>> identifyWithServiceResponseAsync(List faceIds); + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). + * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). + * @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<IdentifyResult> object if successful. + */ + List identify(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold); + + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). + * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> identifyAsync(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold, final ServiceCallback> serviceCallback); + + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). + * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<IdentifyResult> object + */ + Observable> identifyAsync(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold); + + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). + * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<IdentifyResult> object + */ + Observable>> identifyWithServiceResponseAsync(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold); /** * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. * - * @param faceId1 FaceId of the first face, comes from Face - Detect. - * @param faceId2 FaceId of the second face, comes from Face - Detect. + * @param faceId1 FaceId of the first face, comes from Face - Detect + * @param faceId2 FaceId of the second face, comes from Face - Detect * @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 @@ -295,257 +382,407 @@ interface FacesIdentifyDefinition extends /** * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. * - * @param faceId1 FaceId of the first face, comes from Face - Detect. - * @param faceId2 FaceId of the second face, comes from Face - Detect. + * @param faceId1 FaceId of the first face, comes from Face - Detect + * @param faceId2 FaceId of the second face, comes from Face - Detect + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture verifyFaceToFaceAsync(UUID faceId1, UUID faceId2, final ServiceCallback serviceCallback); + + /** + * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. + * + * @param faceId1 FaceId of the first face, comes from Face - Detect + * @param faceId2 FaceId of the second face, comes from Face - Detect * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the VerifyResult object */ Observable verifyFaceToFaceAsync(UUID faceId1, UUID faceId2); + /** + * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. + * + * @param faceId1 FaceId of the first face, comes from Face - Detect + * @param faceId2 FaceId of the second face, comes from Face - Detect + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the VerifyResult object + */ + Observable> verifyFaceToFaceWithServiceResponseAsync(UUID faceId1, UUID faceId2); /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and - * attributes. + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). * - * @param url Publicly reachable URL of an image. - * @param detectWithUrlOptionalParameter the object representing the optional parameters to be set before calling this API + * @param url Publicly reachable URL of an image * @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<DetectedFace> object if successful. */ - - List detectWithUrl(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter); + List detectWithUrl(String url); + + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> detectWithUrlAsync(String url, final ServiceCallback> serviceCallback); /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and - * attributes. + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). * - * @param url Publicly reachable URL of an image. - * @param detectWithUrlOptionalParameter the object representing the optional parameters to be set before calling this API + * @param url Publicly reachable URL of an image * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<DetectedFace> object */ - - Observable> detectWithUrlAsync(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter); - - /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and - * attributes. - * - * @return the first stage of the detectWithUrl call - */ - FacesDetectWithUrlDefinitionStages.WithUrl detectWithUrl(); - - /** - * Grouping of detectWithUrl definition stages. - */ - interface FacesDetectWithUrlDefinitionStages { - /** - * The stage of the definition to be specify url. - */ - interface WithUrl { - /** - * Publicly reachable URL of an image. - * - * @return next definition stage - */ - FacesDetectWithUrlDefinitionStages.WithExecute withUrl(String url); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * A value indicating whether the operation should return faceIds of detected faces. - * - * @return next definition stage - */ - FacesDetectWithUrlDefinitionStages.WithExecute withReturnFaceId(Boolean returnFaceId); - - /** - * A value indicating whether the operation should return landmarks of the detected faces. - * - * @return next definition stage - */ - FacesDetectWithUrlDefinitionStages.WithExecute withReturnFaceLandmarks(Boolean returnFaceLandmarks); - - /** - * Analyze and return the one or more specified face attributes in the comma-separated string like - * "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, - * facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and - * time cost. - * - * @return next definition stage - */ - FacesDetectWithUrlDefinitionStages.WithExecute withReturnFaceAttributes(List returnFaceAttributes); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FacesDetectWithUrlDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the List<DetectedFace> object if successful. - */ - List execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the List<DetectedFace> object - */ - Observable> executeAsync(); - } - } - - /** - * The entirety of detectWithUrl definition. - */ - interface FacesDetectWithUrlDefinition extends - FacesDetectWithUrlDefinitionStages.WithUrl, - FacesDetectWithUrlDefinitionStages.WithExecute { - } + Observable> detectWithUrlAsync(String url); + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + Observable>> detectWithUrlWithServiceResponseAsync(String url); + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<DetectedFace> object if successful. + */ + List detectWithUrl(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel); + + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> detectWithUrlAsync(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback); + + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + Observable> detectWithUrlAsync(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel); + + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + Observable>> detectWithUrlWithServiceResponseAsync(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel); + + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @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 VerifyResult object if successful. + */ + VerifyResult verifyFaceToPerson(UUID faceId, UUID personId); + + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture verifyFaceToPersonAsync(UUID faceId, UUID personId, final ServiceCallback serviceCallback); + + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the VerifyResult object + */ + Observable verifyFaceToPersonAsync(UUID faceId, UUID personId); /** * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. * - * @param faceId FaceId the face, comes from Face - Detect. - * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is - * created in Person Groups.Create. - * @param personId Specify a certain person in a person group. personId is created in Persons.Create. + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the VerifyResult object + */ + Observable> verifyFaceToPersonWithServiceResponseAsync(UUID faceId, UUID personId); + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * @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 VerifyResult object if successful. */ - VerifyResult verifyFaceToPerson(UUID faceId, String personGroupId, UUID personId); + VerifyResult verifyFaceToPerson(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId); + + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture verifyFaceToPersonAsync(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId, final ServiceCallback serviceCallback); /** * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. * - * @param faceId FaceId the face, comes from Face - Detect. - * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is - * created in Person Groups.Create. - * @param personId Specify a certain person in a person group. personId is created in Persons.Create. + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the VerifyResult object */ - Observable verifyFaceToPersonAsync(UUID faceId, String personGroupId, UUID personId); + Observable verifyFaceToPersonAsync(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId); + + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the VerifyResult object + */ + Observable> verifyFaceToPersonWithServiceResponseAsync(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId); + + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @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<DetectedFace> object if successful. + */ + List detectWithStream(byte[] image); + + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> detectWithStreamAsync(byte[] image, final ServiceCallback> serviceCallback); + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + Observable> detectWithStreamAsync(byte[] image); /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and - * attributes. + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + Observable>> detectWithStreamWithServiceResponseAsync(byte[] image); + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. * * @param image An image stream. - * @param detectWithStreamOptionalParameter the object representing the optional parameters to be set before calling this API + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @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<DetectedFace> object if successful. */ - - List detectWithStream(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter); + List detectWithStream(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel); + + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> detectWithStreamAsync(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback); + + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + Observable> detectWithStreamAsync(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel); /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and - * attributes. + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. * * @param image An image stream. - * @param detectWithStreamOptionalParameter the object representing the optional parameters to be set before calling this API + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<DetectedFace> object */ - - Observable> detectWithStreamAsync(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter); - - /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and - * attributes. - * - * @return the first stage of the detectWithStream call - */ - FacesDetectWithStreamDefinitionStages.WithImage detectWithStream(); - - /** - * Grouping of detectWithStream definition stages. - */ - interface FacesDetectWithStreamDefinitionStages { - /** - * The stage of the definition to be specify image. - */ - interface WithImage { - /** - * An image stream. - * - * @return next definition stage - */ - FacesDetectWithStreamDefinitionStages.WithExecute withImage(byte[] image); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * A value indicating whether the operation should return faceIds of detected faces. - * - * @return next definition stage - */ - FacesDetectWithStreamDefinitionStages.WithExecute withReturnFaceId(Boolean returnFaceId); - - /** - * A value indicating whether the operation should return landmarks of the detected faces. - * - * @return next definition stage - */ - FacesDetectWithStreamDefinitionStages.WithExecute withReturnFaceLandmarks(Boolean returnFaceLandmarks); - - /** - * Analyze and return the one or more specified face attributes in the comma-separated string like - * "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, - * facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and - * time cost. - * - * @return next definition stage - */ - FacesDetectWithStreamDefinitionStages.WithExecute withReturnFaceAttributes(List returnFaceAttributes); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends FacesDetectWithStreamDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the List<DetectedFace> object if successful. - */ - List execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the List<DetectedFace> object - */ - Observable> executeAsync(); - } - } - - /** - * The entirety of detectWithStream definition. - */ - interface FacesDetectWithStreamDefinition extends - FacesDetectWithStreamDefinitionStages.WithImage, - FacesDetectWithStreamDefinitionStages.WithExecute { - } + Observable>> detectWithStreamWithServiceResponseAsync(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel); } diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargeFaceLists.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargeFaceLists.java new file mode 100644 index 000000000000..671e75edc230 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargeFaceLists.java @@ -0,0 +1,1139 @@ +/** + * 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.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.LargeFaceList; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TrainingStatus; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in LargeFaceLists. + */ +public interface LargeFaceLists { + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 largeFaceListId); + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String largeFaceListId, final ServiceCallback serviceCallback); + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable createAsync(String largeFaceListId); + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> createWithServiceResponseAsync(String largeFaceListId); + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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 largeFaceListId, String name, String userData, RecognitionModel recognitionModel); + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String largeFaceListId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback); + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable createAsync(String largeFaceListId, String name, String userData, RecognitionModel recognitionModel); + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> createWithServiceResponseAsync(String largeFaceListId, String name, String userData, RecognitionModel recognitionModel); + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 LargeFaceList object if successful. + */ + LargeFaceList get(String largeFaceListId); + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String largeFaceListId, final ServiceCallback serviceCallback); + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + Observable getAsync(String largeFaceListId); + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + Observable> getWithServiceResponseAsync(String largeFaceListId); + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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 LargeFaceList object if successful. + */ + LargeFaceList get(String largeFaceListId, Boolean returnRecognitionModel); + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String largeFaceListId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback); + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + Observable getAsync(String largeFaceListId, Boolean returnRecognitionModel); + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + Observable> getWithServiceResponseAsync(String largeFaceListId, Boolean returnRecognitionModel); + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 largeFaceListId); + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String largeFaceListId, final ServiceCallback serviceCallback); + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String largeFaceListId); + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String largeFaceListId); + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 largeFaceListId, String name, String userData); + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String largeFaceListId, String name, String userData, final ServiceCallback serviceCallback); + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String largeFaceListId, String name, String userData); + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String largeFaceListId, String name, String userData); + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 largeFaceListId); + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteAsync(String largeFaceListId, final ServiceCallback serviceCallback); + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteAsync(String largeFaceListId); + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteWithServiceResponseAsync(String largeFaceListId); + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 largeFaceListId); + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getTrainingStatusAsync(String largeFaceListId, final ServiceCallback serviceCallback); + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + Observable getTrainingStatusAsync(String largeFaceListId); + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + Observable> getTrainingStatusWithServiceResponseAsync(String largeFaceListId); + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @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<LargeFaceList> object if successful. + */ + List list(); + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(final ServiceCallback> serviceCallback); + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + Observable> listAsync(); + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + Observable>> listWithServiceResponseAsync(); + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<LargeFaceList> object if successful. + */ + List list(Boolean returnRecognitionModel); + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(Boolean returnRecognitionModel, final ServiceCallback> serviceCallback); + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + Observable> listAsync(Boolean returnRecognitionModel); + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + Observable>> listWithServiceResponseAsync(Boolean returnRecognitionModel); + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 largeFaceListId); + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture trainAsync(String largeFaceListId, final ServiceCallback serviceCallback); + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable trainAsync(String largeFaceListId); + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> trainWithServiceResponseAsync(String largeFaceListId); + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 deleteFace(String largeFaceListId, UUID persistedFaceId); + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteFaceAsync(String largeFaceListId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteFaceAsync(String largeFaceListId, UUID persistedFaceId); + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 PersistedFace object if successful. + */ + PersistedFace getFace(String largeFaceListId, UUID persistedFaceId); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getFaceAsync(String largeFaceListId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable getFaceAsync(String largeFaceListId, UUID persistedFaceId); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> getFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId); + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 updateFace(String largeFaceListId, UUID persistedFaceId); + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateFaceAsync(String largeFaceListId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateFaceAsync(String largeFaceListId, UUID persistedFaceId); + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId); + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @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 updateFace(String largeFaceListId, UUID persistedFaceId, String userData); + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateFaceAsync(String largeFaceListId, UUID persistedFaceId, String userData, final ServiceCallback serviceCallback); + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateFaceAsync(String largeFaceListId, UUID persistedFaceId, String userData); + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId, String userData); + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromUrl(String largeFaceListId, String url); + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String largeFaceListId, String url, final ServiceCallback serviceCallback); + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromUrlAsync(String largeFaceListId, String url); + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String largeFaceListId, String url); + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromUrl(String largeFaceListId, String url, String userData, List targetFace); + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String largeFaceListId, String url, String userData, List targetFace, final ServiceCallback serviceCallback); + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromUrlAsync(String largeFaceListId, String url, String userData, List targetFace); + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String largeFaceListId, String url, String userData, List targetFace); + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @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<PersistedFace> object if successful. + */ + List listFaces(String largeFaceListId); + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listFacesAsync(String largeFaceListId, final ServiceCallback> serviceCallback); + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + Observable> listFacesAsync(String largeFaceListId); + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + Observable>> listFacesWithServiceResponseAsync(String largeFaceListId); + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @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<PersistedFace> object if successful. + */ + List listFaces(String largeFaceListId, String start, Integer top); + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listFacesAsync(String largeFaceListId, String start, Integer top, final ServiceCallback> serviceCallback); + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + Observable> listFacesAsync(String largeFaceListId, String start, Integer top); + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + Observable>> listFacesWithServiceResponseAsync(String largeFaceListId, String start, Integer top); + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromStream(String largeFaceListId, byte[] image); + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String largeFaceListId, byte[] image, final ServiceCallback serviceCallback); + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String largeFaceListId, byte[] image); + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromStreamWithServiceResponseAsync(String largeFaceListId, byte[] image); + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromStream(String largeFaceListId, byte[] image, String userData, List targetFace); + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String largeFaceListId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback); + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String largeFaceListId, byte[] image, String userData, List targetFace); + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromStreamWithServiceResponseAsync(String largeFaceListId, byte[] image, String userData, List targetFace); + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroupPersons.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroupPersons.java new file mode 100644 index 000000000000..855591cca01d --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroupPersons.java @@ -0,0 +1,823 @@ +/** + * 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.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.Person; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in LargePersonGroupPersons. + */ +public interface LargePersonGroupPersons { + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large 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 Person object if successful. + */ + Person create(String largePersonGroupId); + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String largePersonGroupId, final ServiceCallback serviceCallback); + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable createAsync(String largePersonGroupId); + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable> createWithServiceResponseAsync(String largePersonGroupId); + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 Person object if successful. + */ + Person create(String largePersonGroupId, String name, String userData); + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String largePersonGroupId, String name, String userData, final ServiceCallback serviceCallback); + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable createAsync(String largePersonGroupId, String name, String userData); + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable> createWithServiceResponseAsync(String largePersonGroupId, String name, String userData); + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large 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 List<Person> object if successful. + */ + List list(String largePersonGroupId); + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(String largePersonGroupId, final ServiceCallback> serviceCallback); + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + Observable> listAsync(String largePersonGroupId); + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + Observable>> listWithServiceResponseAsync(String largePersonGroupId); + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @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<Person> object if successful. + */ + List list(String largePersonGroupId, String start, Integer top); + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(String largePersonGroupId, String start, Integer top, final ServiceCallback> serviceCallback); + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + Observable> listAsync(String largePersonGroupId, String start, Integer top); + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + Observable>> listWithServiceResponseAsync(String largePersonGroupId, String start, Integer top); + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @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 largePersonGroupId, UUID personId); + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteAsync(String largePersonGroupId, UUID personId, final ServiceCallback serviceCallback); + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteAsync(String largePersonGroupId, UUID personId); + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteWithServiceResponseAsync(String largePersonGroupId, UUID personId); + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @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 Person object if successful. + */ + Person get(String largePersonGroupId, UUID personId); + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String largePersonGroupId, UUID personId, final ServiceCallback serviceCallback); + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable getAsync(String largePersonGroupId, UUID personId); + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable> getWithServiceResponseAsync(String largePersonGroupId, UUID personId); + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @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 largePersonGroupId, UUID personId); + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String largePersonGroupId, UUID personId, final ServiceCallback serviceCallback); + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String largePersonGroupId, UUID personId); + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String largePersonGroupId, UUID personId); + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 largePersonGroupId, UUID personId, String name, String userData); + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String largePersonGroupId, UUID personId, String name, String userData, final ServiceCallback serviceCallback); + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String largePersonGroupId, UUID personId, String name, String userData); + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String largePersonGroupId, UUID personId, String name, String userData); + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 deleteFace(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 PersistedFace object if successful. + */ + PersistedFace getFace(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable getFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> getFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 updateFace(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId); + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId); + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @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 updateFace(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData); + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData, final ServiceCallback serviceCallback); + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData); + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromUrl(String largePersonGroupId, UUID personId, String url); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url, final ServiceCallback serviceCallback); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String largePersonGroupId, UUID personId, String url); + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromUrl(String largePersonGroupId, UUID personId, String url, String userData, List targetFace); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url, String userData, List targetFace, final ServiceCallback serviceCallback); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url, String userData, List targetFace); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String largePersonGroupId, UUID personId, String url, String userData, List targetFace); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromStream(String largePersonGroupId, UUID personId, byte[] image); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image, final ServiceCallback serviceCallback); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromStreamWithServiceResponseAsync(String largePersonGroupId, UUID personId, byte[] image); + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromStream(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromStreamWithServiceResponseAsync(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace); + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroups.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroups.java new file mode 100644 index 000000000000..5a4bbe45fe9f --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/LargePersonGroups.java @@ -0,0 +1,618 @@ +/** + * 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.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.LargePersonGroup; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TrainingStatus; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; +import java.util.List; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in LargePersonGroups. + */ +public interface LargePersonGroups { + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large 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 create(String largePersonGroupId); + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String largePersonGroupId, final ServiceCallback serviceCallback); + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable createAsync(String largePersonGroupId); + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> createWithServiceResponseAsync(String largePersonGroupId); + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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 largePersonGroupId, String name, String userData, RecognitionModel recognitionModel); + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String largePersonGroupId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback); + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable createAsync(String largePersonGroupId, String name, String userData, RecognitionModel recognitionModel); + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> createWithServiceResponseAsync(String largePersonGroupId, String name, String userData, RecognitionModel recognitionModel); + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large 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 largePersonGroupId); + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteAsync(String largePersonGroupId, final ServiceCallback serviceCallback); + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteAsync(String largePersonGroupId); + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteWithServiceResponseAsync(String largePersonGroupId); + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large 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 LargePersonGroup object if successful. + */ + LargePersonGroup get(String largePersonGroupId); + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String largePersonGroupId, final ServiceCallback serviceCallback); + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + Observable getAsync(String largePersonGroupId); + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + Observable> getWithServiceResponseAsync(String largePersonGroupId); + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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 LargePersonGroup object if successful. + */ + LargePersonGroup get(String largePersonGroupId, Boolean returnRecognitionModel); + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String largePersonGroupId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback); + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + Observable getAsync(String largePersonGroupId, Boolean returnRecognitionModel); + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + Observable> getWithServiceResponseAsync(String largePersonGroupId, Boolean returnRecognitionModel); + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large 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 update(String largePersonGroupId); + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String largePersonGroupId, final ServiceCallback serviceCallback); + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String largePersonGroupId); + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String largePersonGroupId); + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 largePersonGroupId, String name, String userData); + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String largePersonGroupId, String name, String userData, final ServiceCallback serviceCallback); + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String largePersonGroupId, String name, String userData); + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String largePersonGroupId, String name, String userData); + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large 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 largePersonGroupId); + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getTrainingStatusAsync(String largePersonGroupId, final ServiceCallback serviceCallback); + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + Observable getTrainingStatusAsync(String largePersonGroupId); + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + Observable> getTrainingStatusWithServiceResponseAsync(String largePersonGroupId); + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @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<LargePersonGroup> object if successful. + */ + List list(); + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(final ServiceCallback> serviceCallback); + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + Observable> listAsync(); + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + Observable>> listWithServiceResponseAsync(); + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<LargePersonGroup> object if successful. + */ + List list(String start, Integer top, Boolean returnRecognitionModel); + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(String start, Integer top, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback); + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + Observable> listAsync(String start, Integer top, Boolean returnRecognitionModel); + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + Observable>> listWithServiceResponseAsync(String start, Integer top, Boolean returnRecognitionModel); + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large 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 largePersonGroupId); + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture trainAsync(String largePersonGroupId, final ServiceCallback serviceCallback); + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable trainAsync(String largePersonGroupId); + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> trainWithServiceResponseAsync(String largePersonGroupId); + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroupPersons.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroupPersons.java index 851f772de3c4..6c4f4acb7821 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroupPersons.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroupPersons.java @@ -8,15 +8,13 @@ package com.microsoft.azure.cognitiveservices.vision.faceapi; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.CreatePersonGroupPersonsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ListPersonGroupPersonsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdatePersonGroupPersonsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateFaceOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddPersonFaceFromUrlOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddPersonFaceFromStreamOptionalParameter; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.Person; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; import java.util.List; import java.util.UUID; import rx.Observable; @@ -30,199 +28,174 @@ public interface PersonGroupPersons { * Create a new person in a specified person group. * * @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 * @return the Person object if successful. */ - - Person create(String personGroupId, CreatePersonGroupPersonsOptionalParameter createOptionalParameter); + Person create(String personGroupId); + + /** + * Create a new person in a specified person group. + * + * @param personGroupId Id referencing a particular person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String personGroupId, final ServiceCallback serviceCallback); /** * Create a new person in a specified person group. * * @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 the observable to the Person object */ - - Observable createAsync(String personGroupId, CreatePersonGroupPersonsOptionalParameter createOptionalParameter); + Observable createAsync(String personGroupId); /** * Create a new person in a specified person group. * - * @return the first stage of the create call - */ - PersonGroupPersonsCreateDefinitionStages.WithPersonGroupId create(); - - /** - * Grouping of create definition stages. - */ - interface PersonGroupPersonsCreateDefinitionStages { - /** - * The stage of the definition to be specify personGroupId. - */ - interface WithPersonGroupId { - /** - * Id referencing a particular person group. - * - * @return next definition stage - */ - PersonGroupPersonsCreateDefinitionStages.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 - */ - PersonGroupPersonsCreateDefinitionStages.WithExecute withName(String name); - - /** - * User specified data. Length should not exceed 16KB. - * - * @return next definition stage - */ - PersonGroupPersonsCreateDefinitionStages.WithExecute withUserData(String userData); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends PersonGroupPersonsCreateDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the Person object if successful. - */ - Person execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the Person object - */ - Observable executeAsync(); - } - } - - /** - * The entirety of create definition. - */ - interface PersonGroupPersonsCreateDefinition extends - PersonGroupPersonsCreateDefinitionStages.WithPersonGroupId, - PersonGroupPersonsCreateDefinitionStages.WithExecute { - } - - /** - * List all persons in a person group, and retrieve person information (including personId, name, userData and - * persistedFaceIds of registered faces of the person). - * - * @param personGroupId Id referencing a particular person group. - * @param listOptionalParameter the object representing the optional parameters to be set before calling this API + * @param personGroupId Id referencing a particular person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable> createWithServiceResponseAsync(String personGroupId); + /** + * Create a new person in a specified person group. + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. * @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<Person> object if successful. + * @return the Person object if successful. */ - - List list(String personGroupId, ListPersonGroupPersonsOptionalParameter listOptionalParameter); + Person create(String personGroupId, String name, String userData); /** - * List all persons in a person group, and retrieve person information (including personId, name, userData and - * persistedFaceIds of registered faces of the person). + * Create a new person in a specified person group. * * @param personGroupId Id referencing a particular person group. - * @param listOptionalParameter the object representing the optional parameters to be set before calling this API + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return the observable to the List<Person> object + * @return the {@link ServiceFuture} object */ - - Observable> listAsync(String personGroupId, ListPersonGroupPersonsOptionalParameter listOptionalParameter); + ServiceFuture createAsync(String personGroupId, String name, String userData, final ServiceCallback serviceCallback); /** - * List all persons in a person group, and retrieve person information (including personId, name, userData and - * persistedFaceIds of registered faces of the person). + * Create a new person in a specified person group. * - * @return the first stage of the list call + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object */ - PersonGroupPersonsListDefinitionStages.WithPersonGroupId list(); + Observable createAsync(String personGroupId, String name, String userData); /** - * Grouping of list definition stages. + * Create a new person in a specified person group. + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object */ - interface PersonGroupPersonsListDefinitionStages { - /** - * The stage of the definition to be specify personGroupId. - */ - interface WithPersonGroupId { - /** - * Id referencing a particular person group. - * - * @return next definition stage - */ - PersonGroupPersonsListDefinitionStages.WithExecute withPersonGroupId(String personGroupId); - } + Observable> createWithServiceResponseAsync(String personGroupId, String name, String userData); - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * Starting person id to return (used to list a range of persons). - * - * @return next definition stage - */ - PersonGroupPersonsListDefinitionStages.WithExecute withStart(String start); + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @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 List<Person> object if successful. + */ + List list(String personGroupId); - /** - * Number of persons to return starting with the person id indicated by the 'start' parameter. - * - * @return next definition stage - */ - PersonGroupPersonsListDefinitionStages.WithExecute withTop(Integer top); + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(String personGroupId, final ServiceCallback> serviceCallback); - } + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + Observable> listAsync(String personGroupId); - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends PersonGroupPersonsListDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the List<Person> object if successful. - */ - List execute(); + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + Observable>> listWithServiceResponseAsync(String personGroupId); + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @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<Person> object if successful. + */ + List list(String personGroupId, String start, Integer top); - /** - * Execute the request asynchronously. - * - * @return the observable to the List<Person> object - */ - Observable> executeAsync(); - } - } + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(String personGroupId, String start, Integer top, final ServiceCallback> serviceCallback); /** - * The entirety of list definition. + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object */ - interface PersonGroupPersonsListDefinition extends - PersonGroupPersonsListDefinitionStages.WithPersonGroupId, - PersonGroupPersonsListDefinitionStages.WithExecute { - } + Observable> listAsync(String personGroupId, String start, Integer top); + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + Observable>> listWithServiceResponseAsync(String personGroupId, String start, Integer top); /** - * Delete an existing person from a person group. Persisted face images of the person will also be - * deleted. + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -233,17 +206,35 @@ interface PersonGroupPersonsListDefinition extends void delete(String personGroupId, UUID personId); /** - * Delete an existing person from a person group. Persisted face images of the person will also be - * deleted. + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - Observable deleteAsync(String personGroupId, UUID personId); + ServiceFuture deleteAsync(String personGroupId, UUID personId, final ServiceCallback serviceCallback); + /** + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteAsync(String personGroupId, UUID personId); + /** + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteWithServiceResponseAsync(String personGroupId, UUID personId); /** * Retrieve a person's information, including registered persisted faces, name and userData. @@ -257,6 +248,17 @@ interface PersonGroupPersonsListDefinition extends */ Person get(String personGroupId, UUID personId); + /** + * Retrieve a person's information, including registered persisted faces, name and userData. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String personGroupId, UUID personId, final ServiceCallback serviceCallback); + /** * Retrieve a person's information, including registered persisted faces, name and userData. * @@ -267,117 +269,110 @@ interface PersonGroupPersonsListDefinition extends */ Observable getAsync(String personGroupId, UUID personId); + /** + * Retrieve a person's information, including registered persisted faces, name and userData. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + Observable> getWithServiceResponseAsync(String personGroupId, UUID personId); /** * Update name or userData of a person. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. - * @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, UUID personId, UpdatePersonGroupPersonsOptionalParameter updateOptionalParameter); + void update(String personGroupId, UUID personId); /** * Update name or userData of a person. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - - Observable updateAsync(String personGroupId, UUID personId, UpdatePersonGroupPersonsOptionalParameter updateOptionalParameter); + ServiceFuture updateAsync(String personGroupId, UUID personId, final ServiceCallback serviceCallback); /** * Update name or userData of a person. * - * @return the first stage of the update call - */ - PersonGroupPersonsUpdateDefinitionStages.WithPersonGroupId update(); - - /** - * Grouping of update definition stages. - */ - interface PersonGroupPersonsUpdateDefinitionStages { - /** - * The stage of the definition to be specify personGroupId. - */ - interface WithPersonGroupId { - /** - * Id referencing a particular person group. - * - * @return next definition stage - */ - WithPersonId withPersonGroupId(String personGroupId); - } - /** - * The stage of the definition to be specify personId. - */ - interface WithPersonId { - /** - * Id referencing a particular person. - * - * @return next definition stage - */ - PersonGroupPersonsUpdateDefinitionStages.WithExecute withPersonId(UUID personId); - } - - /** - * 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 - */ - PersonGroupPersonsUpdateDefinitionStages.WithExecute withName(String name); - - /** - * User specified data. Length should not exceed 16KB. - * - * @return next definition stage - */ - PersonGroupPersonsUpdateDefinitionStages.WithExecute withUserData(String userData); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends PersonGroupPersonsUpdateDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - */ - void execute(); - - /** - * Execute the request asynchronously. - * - * @return a representation of the deferred computation of this call if successful. - */ - Observable executeAsync(); - } - } - - /** - * The entirety of update definition. - */ - interface PersonGroupPersonsUpdateDefinition extends - PersonGroupPersonsUpdateDefinitionStages.WithPersonGroupId, - PersonGroupPersonsUpdateDefinitionStages.WithPersonId, - PersonGroupPersonsUpdateDefinitionStages.WithExecute { - } - - - /** - * Delete a face from a person. Relative image for the persisted face will also be deleted. + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String personGroupId, UUID personId); + + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String personGroupId, UUID personId); + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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, UUID personId, String name, String userData); + + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String personGroupId, UUID personId, String name, String userData, final ServiceCallback serviceCallback); + + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String personGroupId, UUID personId, String name, String userData); + + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String personGroupId, UUID personId, String name, String userData); + + /** + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -389,21 +384,44 @@ interface PersonGroupPersonsUpdateDefinition extends void deleteFace(String personGroupId, UUID personId, UUID persistedFaceId); /** - * Delete a face from a person. Relative image for the persisted face will also be deleted. + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - Observable deleteFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId); + ServiceFuture deleteFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback); + /** + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId); + /** + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId); /** - * Retrieve information about a persisted face (specified by persistedFaceId, personId and its - * belonging personGroupId). + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId). * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -416,8 +434,19 @@ interface PersonGroupPersonsUpdateDefinition extends PersistedFace getFace(String personGroupId, UUID personId, UUID persistedFaceId); /** - * Retrieve information about a persisted face (specified by persistedFaceId, personId and its - * belonging personGroupId). + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId). + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback); + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId). * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -427,377 +456,424 @@ interface PersonGroupPersonsUpdateDefinition extends */ Observable getFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId); + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging personGroupId). + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> getFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId); /** - * Update a person persisted face's userData field. + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. - * @param updateFaceOptionalParameter 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 updateFace(String personGroupId, UUID personId, UUID persistedFaceId, UpdateFaceOptionalParameter updateFaceOptionalParameter); + void updateFace(String personGroupId, UUID personId, UUID persistedFaceId); + + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback); /** - * Update a person persisted face's userData field. + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. - * @param updateFaceOptionalParameter 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 updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, UpdateFaceOptionalParameter updateFaceOptionalParameter); - - /** - * Update a person persisted face's userData field. - * - * @return the first stage of the updateFace call - */ - PersonGroupPersonsUpdateFaceDefinitionStages.WithPersonGroupId updateFace(); - - /** - * Grouping of updateFace definition stages. - */ - interface PersonGroupPersonsUpdateFaceDefinitionStages { - /** - * The stage of the definition to be specify personGroupId. - */ - interface WithPersonGroupId { - /** - * Id referencing a particular person group. - * - * @return next definition stage - */ - WithPersonId withPersonGroupId(String personGroupId); - } - /** - * The stage of the definition to be specify personId. - */ - interface WithPersonId { - /** - * Id referencing a particular person. - * - * @return next definition stage - */ - WithPersistedFaceId withPersonId(UUID personId); - } - /** - * The stage of the definition to be specify persistedFaceId. - */ - interface WithPersistedFaceId { - /** - * Id referencing a particular persistedFaceId of an existing face. - * - * @return next definition stage - */ - PersonGroupPersonsUpdateFaceDefinitionStages.WithExecute withPersistedFaceId(UUID persistedFaceId); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * User-provided data attached to the face. The size limit is 1KB. - * - * @return next definition stage - */ - PersonGroupPersonsUpdateFaceDefinitionStages.WithExecute withUserData(String userData); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends PersonGroupPersonsUpdateFaceDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - */ - void execute(); - - /** - * Execute the request asynchronously. - * - * @return a representation of the deferred computation of this call if successful. - */ - Observable executeAsync(); - } - } - - /** - * The entirety of updateFace definition. - */ - interface PersonGroupPersonsUpdateFaceDefinition extends - PersonGroupPersonsUpdateFaceDefinitionStages.WithPersonGroupId, - PersonGroupPersonsUpdateFaceDefinitionStages.WithPersonId, - PersonGroupPersonsUpdateFaceDefinitionStages.WithPersistedFaceId, - PersonGroupPersonsUpdateFaceDefinitionStages.WithExecute { - } - - /** - * Add a representative face to a person for identification. The input face is specified as an image with a - * targetFace rectangle. - * - * @param personGroupId Id referencing a particular person group. - * @param personId Id referencing a particular person. - * @param url Publicly reachable URL of an image. - * @param addPersonFaceFromUrlOptionalParameter the object representing the optional parameters to be set before calling this API + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId); + + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId); + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @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 updateFace(String personGroupId, UUID personId, UUID persistedFaceId, String userData); + + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, String userData, final ServiceCallback serviceCallback); + + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, String userData); + + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId, String userData); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromUrl(String personGroupId, UUID personId, String url); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String personGroupId, UUID personId, String url, final ServiceCallback serviceCallback); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromUrlAsync(String personGroupId, UUID personId, String url); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String personGroupId, UUID personId, String url); + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. * @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 PersistedFace object if successful. */ - - PersistedFace addPersonFaceFromUrl(String personGroupId, UUID personId, String url, AddPersonFaceFromUrlOptionalParameter addPersonFaceFromUrlOptionalParameter); + PersistedFace addFaceFromUrl(String personGroupId, UUID personId, String url, String userData, List targetFace); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromUrlAsync(String personGroupId, UUID personId, String url, String userData, List targetFace, final ServiceCallback serviceCallback); /** - * Add a representative face to a person for identification. The input face is specified as an image with a - * targetFace rectangle. + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. - * @param url Publicly reachable URL of an image. - * @param addPersonFaceFromUrlOptionalParameter the object representing the optional parameters to be set before calling this API + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the PersistedFace object */ - - Observable addPersonFaceFromUrlAsync(String personGroupId, UUID personId, String url, AddPersonFaceFromUrlOptionalParameter addPersonFaceFromUrlOptionalParameter); - - /** - * Add a representative face to a person for identification. The input face is specified as an image with a - * targetFace rectangle. - * - * @return the first stage of the addPersonFaceFromUrl call - */ - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithPersonGroupId addPersonFaceFromUrl(); - - /** - * Grouping of addPersonFaceFromUrl definition stages. - */ - interface PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages { - /** - * The stage of the definition to be specify personGroupId. - */ - interface WithPersonGroupId { - /** - * Id referencing a particular person group. - * - * @return next definition stage - */ - WithPersonId withPersonGroupId(String personGroupId); - } - /** - * The stage of the definition to be specify personId. - */ - interface WithPersonId { - /** - * Id referencing a particular person. - * - * @return next definition stage - */ - WithUrl withPersonId(UUID personId); - } - /** - * The stage of the definition to be specify url. - */ - interface WithUrl { - /** - * Publicly reachable URL of an image. - * - * @return next definition stage - */ - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithExecute withUrl(String url); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * User-specified data about the face for any purpose. The maximum length is 1KB. - * - * @return next definition stage - */ - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithExecute withUserData(String userData); - - /** - * A face rectangle to specify the target face to be added to a person in the format of - * "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the - * image, targetFace is required to specify which face to add. No targetFace means there is only one face - * detected in the entire image. - * - * @return next definition stage - */ - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithExecute withTargetFace(List targetFace); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the PersistedFace object if successful. - */ - PersistedFace execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the PersistedFace object - */ - Observable executeAsync(); - } - } - - /** - * The entirety of addPersonFaceFromUrl definition. - */ - interface PersonGroupPersonsAddPersonFaceFromUrlDefinition extends - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithPersonGroupId, - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithPersonId, - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithUrl, - PersonGroupPersonsAddPersonFaceFromUrlDefinitionStages.WithExecute { - } - - /** - * Add a representative face to a person for identification. The input face is specified as an image with a - * targetFace rectangle. + Observable addFaceFromUrlAsync(String personGroupId, UUID personId, String url, String userData, List targetFace); + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromUrlWithServiceResponseAsync(String personGroupId, UUID personId, String url, String userData, List targetFace); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param image An image stream. - * @param addPersonFaceFromStreamOptionalParameter 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 PersistedFace object if successful. */ - - PersistedFace addPersonFaceFromStream(String personGroupId, UUID personId, byte[] image, AddPersonFaceFromStreamOptionalParameter addPersonFaceFromStreamOptionalParameter); + PersistedFace addFaceFromStream(String personGroupId, UUID personId, byte[] image); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, final ServiceCallback serviceCallback); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable> addFaceFromStreamWithServiceResponseAsync(String personGroupId, UUID personId, byte[] image); + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + PersistedFace addFaceFromStream(String personGroupId, UUID personId, byte[] image, String userData, List targetFace); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback); + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + Observable addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, String userData, List targetFace); /** - * Add a representative face to a person for identification. The input face is specified as an image with a - * targetFace rectangle. + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param image An image stream. - * @param addPersonFaceFromStreamOptionalParameter the object representing the optional parameters to be set before calling this API + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the PersistedFace object */ - - Observable addPersonFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, AddPersonFaceFromStreamOptionalParameter addPersonFaceFromStreamOptionalParameter); - - /** - * Add a representative face to a person for identification. The input face is specified as an image with a - * targetFace rectangle. - * - * @return the first stage of the addPersonFaceFromStream call - */ - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithPersonGroupId addPersonFaceFromStream(); - - /** - * Grouping of addPersonFaceFromStream definition stages. - */ - interface PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages { - /** - * The stage of the definition to be specify personGroupId. - */ - interface WithPersonGroupId { - /** - * Id referencing a particular person group. - * - * @return next definition stage - */ - WithPersonId withPersonGroupId(String personGroupId); - } - /** - * The stage of the definition to be specify personId. - */ - interface WithPersonId { - /** - * Id referencing a particular person. - * - * @return next definition stage - */ - WithImage withPersonId(UUID personId); - } - /** - * The stage of the definition to be specify image. - */ - interface WithImage { - /** - * An image stream. - * - * @return next definition stage - */ - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithExecute withImage(byte[] image); - } - - /** - * The stage of the definition which allows for any other optional settings to be specified. - */ - interface WithAllOptions { - /** - * User-specified data about the face for any purpose. The maximum length is 1KB. - * - * @return next definition stage - */ - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithExecute withUserData(String userData); - - /** - * A face rectangle to specify the target face to be added to a person in the format of - * "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the - * image, targetFace is required to specify which face to add. No targetFace means there is only one face - * detected in the entire image. - * - * @return next definition stage - */ - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithExecute withTargetFace(List targetFace); - - } - - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - * @return the PersistedFace object if successful. - */ - PersistedFace execute(); - - /** - * Execute the request asynchronously. - * - * @return the observable to the PersistedFace object - */ - Observable executeAsync(); - } - } - - /** - * The entirety of addPersonFaceFromStream definition. - */ - interface PersonGroupPersonsAddPersonFaceFromStreamDefinition extends - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithPersonGroupId, - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithPersonId, - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithImage, - PersonGroupPersonsAddPersonFaceFromStreamDefinitionStages.WithExecute { - } + Observable> addFaceFromStreamWithServiceResponseAsync(String personGroupId, UUID personId, byte[] image, String userData, List targetFace); } diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroups.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroups.java index 59496a6f4ca8..3acbf12df612 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroups.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/PersonGroups.java @@ -8,12 +8,14 @@ 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.RecognitionModel; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TrainingStatus; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; import java.util.List; import rx.Observable; @@ -23,102 +25,174 @@ */ public interface PersonGroups { /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * * @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); + void create(String personGroupId); /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * * @param personGroupId Id referencing a particular person group. - * @param createOptionalParameter the object representing the optional parameters to be set before calling this API + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - - Observable createAsync(String personGroupId, CreatePersonGroupsOptionalParameter createOptionalParameter); + ServiceFuture createAsync(String personGroupId, final ServiceCallback serviceCallback); /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * - * @return the first stage of the create call + * @param personGroupId Id referencing a particular person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - PersonGroupsCreateDefinitionStages.WithPersonGroupId create(); + Observable createAsync(String personGroupId); /** - * Grouping of create definition stages. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - 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(); + Observable> createWithServiceResponseAsync(String personGroupId); + /** + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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, String name, String userData, RecognitionModel recognitionModel); - /** - * Execute the request asynchronously. - * - * @return a representation of the deferred computation of this call if successful. - */ - Observable executeAsync(); - } - } + /** + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture createAsync(String personGroupId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback); /** - * The entirety of create definition. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - interface PersonGroupsCreateDefinition extends - PersonGroupsCreateDefinitionStages.WithPersonGroupId, - PersonGroupsCreateDefinitionStages.WithExecute { - } + Observable createAsync(String personGroupId, String name, String userData, RecognitionModel recognitionModel); + /** + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> createWithServiceResponseAsync(String personGroupId, String name, String userData, RecognitionModel recognitionModel); /** - * Delete an existing person group. Persisted face images of all people in the person group will also - * be deleted. + * Delete an existing person group. Persisted face features 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 @@ -128,19 +202,35 @@ interface PersonGroupsCreateDefinition extends void delete(String personGroupId); /** - * Delete an existing person group. Persisted face images of all people in the person group will also - * be deleted. + * Delete an existing person group. Persisted face features of all people in the person group will also be deleted. * * @param personGroupId Id referencing a particular person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - Observable deleteAsync(String personGroupId); + ServiceFuture deleteAsync(String personGroupId, final ServiceCallback serviceCallback); + /** + * Delete an existing person group. Persisted face features 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 the {@link ServiceResponse} object if successful. + */ + Observable deleteAsync(String personGroupId); + /** + * Delete an existing person group. Persisted face features 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 the {@link ServiceResponse} object if successful. + */ + Observable> deleteWithServiceResponseAsync(String personGroupId); /** - * Retrieve the information of a person group, including its name and userData. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -151,7 +241,17 @@ interface PersonGroupsCreateDefinition extends PersonGroup get(String personGroupId); /** - * Retrieve the information of a person group, including its name and userData. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). + * + * @param personGroupId Id referencing a particular person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(String personGroupId, final ServiceCallback serviceCallback); + + /** + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -159,103 +259,139 @@ interface PersonGroupsCreateDefinition extends */ Observable 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. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). + * + * @param personGroupId Id referencing a particular person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersonGroup object + */ + Observable> getWithServiceResponseAsync(String personGroupId); + /** + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @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. */ - - void update(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter); + PersonGroup get(String personGroupId, Boolean returnRecognitionModel); /** - * Update an existing person group's display name and userData. The properties which does not appear in request - * body will not be updated. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return a representation of the deferred computation of this call if successful. + * @return the {@link ServiceFuture} object */ - - Observable updateAsync(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter); + ServiceFuture getAsync(String personGroupId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback); /** - * Update an existing person group's display name and userData. The properties which does not appear in request - * body will not be updated. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * - * @return the first stage of the update call + * @param personGroupId Id referencing a particular person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersonGroup object */ - PersonGroupsUpdateDefinitionStages.WithPersonGroupId update(); + Observable getAsync(String personGroupId, Boolean returnRecognitionModel); /** - * Grouping of update definition stages. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). + * + * @param personGroupId Id referencing a particular person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersonGroup object */ - 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); - } + Observable> getWithServiceResponseAsync(String personGroupId, Boolean returnRecognitionModel); - /** - * 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); + /** + * 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. + * @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); - /** - * User specified data. Length should not exceed 16KB. - * - * @return next definition stage - */ - PersonGroupsUpdateDefinitionStages.WithExecute withUserData(String userData); + /** + * 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 serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String personGroupId, final ServiceCallback serviceCallback); - } + /** + * 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. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(String personGroupId); - /** - * The last stage of the definition which will make the operation call. - */ - interface WithExecute extends PersonGroupsUpdateDefinitionStages.WithAllOptions { - /** - * Execute the request. - * - */ - void execute(); + /** + * 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. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(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 name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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, String name, String userData); - /** - * Execute the request asynchronously. - * - * @return a representation of the deferred computation of this call if successful. - */ - Observable executeAsync(); - } - } + /** + * 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 name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(String personGroupId, String name, String userData, final ServiceCallback serviceCallback); /** - * The entirety of update definition. + * 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 name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. */ - interface PersonGroupsUpdateDefinition extends - PersonGroupsUpdateDefinitionStages.WithPersonGroupId, - PersonGroupsUpdateDefinitionStages.WithExecute { - } + Observable updateAsync(String personGroupId, String name, String userData); + /** + * 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 name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(String personGroupId, String name, String userData); /** * Retrieve the training status of a person group (completed or ongoing). @@ -268,6 +404,16 @@ interface PersonGroupsUpdateDefinition extends */ TrainingStatus getTrainingStatus(String personGroupId); + /** + * Retrieve the training status of a person group (completed or ongoing). + * + * @param personGroupId Id referencing a particular person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getTrainingStatusAsync(String personGroupId, final ServiceCallback serviceCallback); + /** * Retrieve the training status of a person group (completed or ongoing). * @@ -277,88 +423,159 @@ interface PersonGroupsUpdateDefinition extends */ Observable getTrainingStatusAsync(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> getTrainingStatusWithServiceResponseAsync(String personGroupId); /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". * - * @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<PersonGroup> object if successful. */ - - List list(ListPersonGroupsOptionalParameter listOptionalParameter); + List list(); /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". * - * @param listOptionalParameter the object representing the optional parameters to be set before calling this API + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation - * @return the observable to the List<PersonGroup> object + * @return the {@link ServiceFuture} object */ - - Observable> listAsync(ListPersonGroupsOptionalParameter listOptionalParameter); + ServiceFuture> listAsync(final ServiceCallback> serviceCallback); /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". * - * @return the first stage of the list call + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersonGroup> object */ - PersonGroupsListDefinitionStages.WithExecute list(); + Observable> listAsync(); /** - * Grouping of list definition stages. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersonGroup> object */ - 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<PersonGroup> object if successful. - */ - List execute(); + Observable>> listWithServiceResponseAsync(); + /** + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List person groups from the least personGroupId greater than the "start". + * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<PersonGroup> object if successful. + */ + List list(String start, Integer top, Boolean returnRecognitionModel); - /** - * Execute the request asynchronously. - * - * @return the observable to the List<PersonGroup> object - */ - Observable> executeAsync(); - } - } + /** + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List person groups from the least personGroupId greater than the "start". + * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(String start, Integer top, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback); /** - * The entirety of list definition. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List person groups from the least personGroupId greater than the "start". + * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersonGroup> object */ - interface PersonGroupsListDefinition extends - PersonGroupsListDefinitionStages.WithExecute { - } + Observable> listAsync(String start, Integer top, Boolean returnRecognitionModel); + /** + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List person groups from the least personGroupId greater than the "start". + * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersonGroup> object + */ + Observable>> listWithServiceResponseAsync(String start, Integer top, Boolean returnRecognitionModel); /** * Queue a person group training task, the training task may not be started immediately. @@ -370,14 +587,32 @@ interface PersonGroupsListDefinition extends */ 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. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture trainAsync(String personGroupId, final ServiceCallback serviceCallback); + /** * 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. + * @return the {@link ServiceResponse} object if successful. */ Observable trainAsync(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 the {@link ServiceResponse} object if successful. + */ + Observable> trainWithServiceResponseAsync(String personGroupId); } diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Snapshots.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Snapshots.java new file mode 100644 index 000000000000..a059629555ba --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/Snapshots.java @@ -0,0 +1,610 @@ +/** + * 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.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.OperationStatus; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.Snapshot; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotApplyHeaders; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotApplyMode; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotObjectType; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotTakeHeaders; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import com.microsoft.rest.ServiceResponseWithHeaders; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in Snapshots. + */ +public interface Snapshots { + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @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 take(SnapshotObjectType type, String objectId, List applyScope); + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture takeAsync(SnapshotObjectType type, String objectId, List applyScope, final ServiceCallback serviceCallback); + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable takeAsync(SnapshotObjectType type, String objectId, List applyScope); + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable> takeWithServiceResponseAsync(SnapshotObjectType type, String objectId, List applyScope); + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @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 take(SnapshotObjectType type, String objectId, List applyScope, String userData); + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture takeAsync(SnapshotObjectType type, String objectId, List applyScope, String userData, final ServiceCallback serviceCallback); + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable takeAsync(SnapshotObjectType type, String objectId, List applyScope, String userData); + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable> takeWithServiceResponseAsync(SnapshotObjectType type, String objectId, List applyScope, String userData); + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @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<Snapshot> object if successful. + */ + List list(); + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(final ServiceCallback> serviceCallback); + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + Observable> listAsync(); + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + Observable>> listWithServiceResponseAsync(); + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @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<Snapshot> object if successful. + */ + List list(SnapshotObjectType type, List applyScope); + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture> listAsync(SnapshotObjectType type, List applyScope, final ServiceCallback> serviceCallback); + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + Observable> listAsync(SnapshotObjectType type, List applyScope); + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + Observable>> listWithServiceResponseAsync(SnapshotObjectType type, List applyScope); + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @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 Snapshot object if successful. + */ + Snapshot get(UUID snapshotId); + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getAsync(UUID snapshotId, final ServiceCallback serviceCallback); + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Snapshot object + */ + Observable getAsync(UUID snapshotId); + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Snapshot object + */ + Observable> getWithServiceResponseAsync(UUID snapshotId); + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @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(UUID snapshotId); + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(UUID snapshotId, final ServiceCallback serviceCallback); + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(UUID snapshotId); + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(UUID snapshotId); + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @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(UUID snapshotId, List applyScope, String userData); + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture updateAsync(UUID snapshotId, List applyScope, String userData, final ServiceCallback serviceCallback); + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable updateAsync(UUID snapshotId, List applyScope, String userData); + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> updateWithServiceResponseAsync(UUID snapshotId, List applyScope, String userData); + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @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(UUID snapshotId); + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteAsync(UUID snapshotId, final ServiceCallback serviceCallback); + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteAsync(UUID snapshotId); + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteWithServiceResponseAsync(UUID snapshotId); + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @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 apply(UUID snapshotId, String objectId); + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture applyAsync(UUID snapshotId, String objectId, final ServiceCallback serviceCallback); + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable applyAsync(UUID snapshotId, String objectId); + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable> applyWithServiceResponseAsync(UUID snapshotId, String objectId); + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @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 apply(UUID snapshotId, String objectId, SnapshotApplyMode mode); + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture applyAsync(UUID snapshotId, String objectId, SnapshotApplyMode mode, final ServiceCallback serviceCallback); + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable applyAsync(UUID snapshotId, String objectId, SnapshotApplyMode mode); + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + Observable> applyWithServiceResponseAsync(UUID snapshotId, String objectId, SnapshotApplyMode mode); + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @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 OperationStatus object if successful. + */ + OperationStatus getOperationStatus(UUID operationId); + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getOperationStatusAsync(UUID operationId, final ServiceCallback serviceCallback); + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the OperationStatus object + */ + Observable getOperationStatusAsync(UUID operationId); + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the OperationStatus object + */ + Observable> getOperationStatusWithServiceResponseAsync(UUID operationId); + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceClientImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceClientImpl.java new file mode 100644 index 000000000000..ae62b58bffb0 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceClientImpl.java @@ -0,0 +1,290 @@ +/** + * 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.implementation; + +import com.microsoft.azure.AzureClient; +import com.microsoft.azure.AzureServiceClient; +import com.microsoft.azure.cognitiveservices.vision.faceapi.FaceClient; +import com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists; +import com.microsoft.azure.cognitiveservices.vision.faceapi.Faces; +import com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists; +import com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons; +import com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups; +import com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons; +import com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups; +import com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots; +import com.microsoft.rest.credentials.ServiceClientCredentials; +import com.microsoft.rest.RestClient; + +/** + * Initializes a new instance of the FaceClientImpl class. + */ +public class FaceClientImpl extends AzureServiceClient implements FaceClient { + /** the {@link AzureClient} used for long running operations. */ + private AzureClient azureClient; + + /** + * Gets the {@link AzureClient} used for long running operations. + * @return the azure client; + */ + public AzureClient getAzureClient() { + return this.azureClient; + } + + /** Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). */ + private String endpoint; + + /** + * Gets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). + * + * @return the endpoint value. + */ + public String endpoint() { + return this.endpoint; + } + + /** + * Sets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com). + * + * @param endpoint the endpoint value. + * @return the service client itself + */ + public FaceClientImpl withEndpoint(String endpoint) { + this.endpoint = endpoint; + return this; + } + + /** The preferred language for the response. */ + private String acceptLanguage; + + /** + * Gets The preferred language for the response. + * + * @return the acceptLanguage value. + */ + public String acceptLanguage() { + return this.acceptLanguage; + } + + /** + * Sets The preferred language for the response. + * + * @param acceptLanguage the acceptLanguage value. + * @return the service client itself + */ + public FaceClientImpl withAcceptLanguage(String acceptLanguage) { + this.acceptLanguage = acceptLanguage; + return this; + } + + /** The retry timeout in seconds for Long Running Operations. Default value is 30. */ + private int longRunningOperationRetryTimeout; + + /** + * Gets The retry timeout in seconds for Long Running Operations. Default value is 30. + * + * @return the longRunningOperationRetryTimeout value. + */ + public int longRunningOperationRetryTimeout() { + return this.longRunningOperationRetryTimeout; + } + + /** + * Sets The retry timeout in seconds for Long Running Operations. Default value is 30. + * + * @param longRunningOperationRetryTimeout the longRunningOperationRetryTimeout value. + * @return the service client itself + */ + public FaceClientImpl withLongRunningOperationRetryTimeout(int longRunningOperationRetryTimeout) { + this.longRunningOperationRetryTimeout = longRunningOperationRetryTimeout; + return this; + } + + /** Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. */ + private boolean generateClientRequestId; + + /** + * Gets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. + * + * @return the generateClientRequestId value. + */ + public boolean generateClientRequestId() { + return this.generateClientRequestId; + } + + /** + * Sets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. + * + * @param generateClientRequestId the generateClientRequestId value. + * @return the service client itself + */ + public FaceClientImpl withGenerateClientRequestId(boolean generateClientRequestId) { + this.generateClientRequestId = generateClientRequestId; + return this; + } + + /** + * The Faces object to access its operations. + */ + private Faces faces; + + /** + * Gets the Faces object to access its operations. + * @return the Faces object. + */ + public Faces faces() { + return this.faces; + } + + /** + * The PersonGroupPersons object to access its operations. + */ + private PersonGroupPersons personGroupPersons; + + /** + * Gets the PersonGroupPersons object to access its operations. + * @return the PersonGroupPersons object. + */ + public PersonGroupPersons personGroupPersons() { + return this.personGroupPersons; + } + + /** + * The PersonGroups object to access its operations. + */ + private PersonGroups personGroups; + + /** + * Gets the PersonGroups object to access its operations. + * @return the PersonGroups object. + */ + public PersonGroups personGroups() { + return this.personGroups; + } + + /** + * The FaceLists object to access its operations. + */ + private FaceLists faceLists; + + /** + * Gets the FaceLists object to access its operations. + * @return the FaceLists object. + */ + public FaceLists faceLists() { + return this.faceLists; + } + + /** + * The LargePersonGroupPersons object to access its operations. + */ + private LargePersonGroupPersons largePersonGroupPersons; + + /** + * Gets the LargePersonGroupPersons object to access its operations. + * @return the LargePersonGroupPersons object. + */ + public LargePersonGroupPersons largePersonGroupPersons() { + return this.largePersonGroupPersons; + } + + /** + * The LargePersonGroups object to access its operations. + */ + private LargePersonGroups largePersonGroups; + + /** + * Gets the LargePersonGroups object to access its operations. + * @return the LargePersonGroups object. + */ + public LargePersonGroups largePersonGroups() { + return this.largePersonGroups; + } + + /** + * The LargeFaceLists object to access its operations. + */ + private LargeFaceLists largeFaceLists; + + /** + * Gets the LargeFaceLists object to access its operations. + * @return the LargeFaceLists object. + */ + public LargeFaceLists largeFaceLists() { + return this.largeFaceLists; + } + + /** + * The Snapshots object to access its operations. + */ + private Snapshots snapshots; + + /** + * Gets the Snapshots object to access its operations. + * @return the Snapshots object. + */ + public Snapshots snapshots() { + return this.snapshots; + } + + /** + * Initializes an instance of FaceClient client. + * + * @param credentials the management credentials for Azure + */ + public FaceClientImpl(ServiceClientCredentials credentials) { + this("https://{Endpoint}/face/v1.0", credentials); + } + + /** + * Initializes an instance of FaceClient client. + * + * @param baseUrl the base URL of the host + * @param credentials the management credentials for Azure + */ + private FaceClientImpl(String baseUrl, ServiceClientCredentials credentials) { + super(baseUrl, credentials); + initialize(); + } + + /** + * Initializes an instance of FaceClient client. + * + * @param restClient the REST client to connect to Azure. + */ + public FaceClientImpl(RestClient restClient) { + super(restClient); + initialize(); + } + + protected void initialize() { + this.acceptLanguage = "en-US"; + this.longRunningOperationRetryTimeout = 30; + this.generateClientRequestId = true; + this.faces = new FacesImpl(restClient().retrofit(), this); + this.personGroupPersons = new PersonGroupPersonsImpl(restClient().retrofit(), this); + this.personGroups = new PersonGroupsImpl(restClient().retrofit(), this); + this.faceLists = new FaceListsImpl(restClient().retrofit(), this); + this.largePersonGroupPersons = new LargePersonGroupPersonsImpl(restClient().retrofit(), this); + this.largePersonGroups = new LargePersonGroupsImpl(restClient().retrofit(), this); + this.largeFaceLists = new LargeFaceListsImpl(restClient().retrofit(), this); + this.snapshots = new SnapshotsImpl(restClient().retrofit(), this); + this.azureClient = new AzureClient(this); + } + + /** + * Gets the User-Agent header for the client. + * + * @return the user agent string. + */ + @Override + public String userAgent() { + return String.format("%s (%s, %s)", super.userAgent(), "FaceClient", "1.0"); + } +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceListsImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceListsImpl.java index 9090fdb56ee0..8a1ead5ac3c9 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceListsImpl.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FaceListsImpl.java @@ -8,10 +8,6 @@ package com.microsoft.azure.cognitiveservices.vision.faceapi.implementation; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.CreateFaceListsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateFaceListsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddFaceFromUrlOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddFaceFromStreamOptionalParameter; import retrofit2.Retrofit; import com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists; import com.google.common.base.Joiner; @@ -19,13 +15,16 @@ import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.FaceList; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ImageUrl; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.MetaDataContract; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.NameAndUserDataContract; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; import com.microsoft.rest.CollectionFormat; import com.microsoft.rest.ServiceCallback; import com.microsoft.rest.ServiceFuture; import com.microsoft.rest.ServiceResponse; import com.microsoft.rest.Validator; +import java.io.InputStream; import java.io.IOException; import java.util.List; import java.util.UUID; @@ -54,7 +53,7 @@ public class FaceListsImpl implements FaceLists { /** The Retrofit service to perform REST calls. */ private FaceListsService service; /** The service client containing this operation class. */ - private FaceAPIImpl client; + private FaceClientImpl client; /** * Initializes an instance of FaceListsImpl. @@ -62,7 +61,7 @@ public class FaceListsImpl implements FaceLists { * @param retrofit the Retrofit instance built from a Retrofit Builder. * @param client the instance of the service client containing this operation class. */ - public FaceListsImpl(Retrofit retrofit, FaceAPIImpl client) { + public FaceListsImpl(Retrofit retrofit, FaceClientImpl client) { this.service = retrofit.create(FaceListsService.class); this.client = client; } @@ -74,15 +73,15 @@ public FaceListsImpl(Retrofit retrofit, FaceAPIImpl client) { interface FaceListsService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists create" }) @PUT("facelists/{faceListId}") - Observable> create(@Path("faceListId") String faceListId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> create(@Path("faceListId") String faceListId, @Header("accept-language") String acceptLanguage, @Body MetaDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists get" }) @GET("facelists/{faceListId}") - Observable> get(@Path("faceListId") String faceListId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> get(@Path("faceListId") String faceListId, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists update" }) @PATCH("facelists/{faceListId}") - Observable> update(@Path("faceListId") String faceListId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> update(@Path("faceListId") String faceListId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists delete" }) @HTTP(path = "facelists/{faceListId}", method = "DELETE", hasBody = true) @@ -90,59 +89,76 @@ interface FaceListsService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists list" }) @GET("facelists") - Observable> list(@Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> list(@Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists deleteFace" }) - @HTTP(path = "facelists/{faceListId}/persistedFaces/{persistedFaceId}", method = "DELETE", hasBody = true) + @HTTP(path = "facelists/{faceListId}/persistedfaces/{persistedFaceId}", method = "DELETE", hasBody = true) Observable> deleteFace(@Path("faceListId") String faceListId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists addFaceFromUrl" }) - @POST("facelists/{faceListId}/persistedFaces") + @POST("facelists/{faceListId}/persistedfaces") Observable> addFaceFromUrl(@Path("faceListId") String faceListId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Header("accept-language") String acceptLanguage, @Body ImageUrl imageUrl, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/octet-stream", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.FaceLists addFaceFromStream" }) - @POST("facelists/{faceListId}/persistedFaces") + @POST("facelists/{faceListId}/persistedfaces") Observable> addFaceFromStream(@Path("faceListId") String faceListId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Body RequestBody image, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); } - /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * * @param faceListId Id referencing a particular face list. - * @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 */ - public void create(String faceListId, CreateFaceListsOptionalParameter createOptionalParameter) { - createWithServiceResponseAsync(faceListId, createOptionalParameter).toBlocking().single().body(); + public void create(String faceListId) { + createWithServiceResponseAsync(faceListId).toBlocking().single().body(); } /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * * @param faceListId Id referencing a particular face list. - * @param createOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture createAsync(String faceListId, CreateFaceListsOptionalParameter createOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(createWithServiceResponseAsync(faceListId, createOptionalParameter), serviceCallback); + public ServiceFuture createAsync(String faceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(faceListId), serviceCallback); } /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * * @param faceListId Id referencing a particular face list. - * @param createOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable createAsync(String faceListId, CreateFaceListsOptionalParameter createOptionalParameter) { - return createWithServiceResponseAsync(faceListId, createOptionalParameter).map(new Func1, Void>() { + public Observable createAsync(String faceListId) { + return createWithServiceResponseAsync(faceListId).map(new Func1, Void>() { @Override public Void call(ServiceResponse response) { return response.body(); @@ -151,47 +167,148 @@ public Void call(ServiceResponse response) { } /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * * @param faceListId Id referencing a particular face list. - * @param createOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable> createWithServiceResponseAsync(String faceListId, CreateFaceListsOptionalParameter createOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> createWithServiceResponseAsync(String faceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); } - final String name = createOptionalParameter != null ? createOptionalParameter.name() : null; - final String userData = createOptionalParameter != null ? createOptionalParameter.userData() : null; + final String name = null; + final String userData = null; + final RecognitionModel recognitionModel = null; + MetaDataContract body = new MetaDataContract(); + body.withName(null); + body.withUserData(null); + body.withRecognitionModel(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(faceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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 + */ + public void create(String faceListId, String name, String userData, RecognitionModel recognitionModel) { + createWithServiceResponseAsync(faceListId, name, userData, recognitionModel).toBlocking().single().body(); + } + + /** + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String faceListId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(faceListId, name, userData, recognitionModel), serviceCallback); + } - return createWithServiceResponseAsync(faceListId, name, userData); + /** + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable createAsync(String faceListId, String name, String userData, RecognitionModel recognitionModel) { + return createWithServiceResponseAsync(faceListId, name, userData, recognitionModel).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); } /** - * Create an empty face list. Up to 64 face lists are allowed to exist in one subscription. + * Create an empty face list with user-specified faceListId, name, an optional userData and recognitionModel. Up to 64 face lists are allowed in one subscription. + <br /> Face list is a list of faces, up to 1,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [FaceList - Add Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the faces. No image will be stored. Only the extracted face features are stored on server until [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> Please consider [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) when the face number is large. It can support up to 1,000,000 faces. + <br />'recognitionModel' should be specified to associate with this face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing face list will use the recognition model that's already associated with the collection. Existing face features in a face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [FaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. * * @param faceListId Id referencing a particular face list. * @param name User defined name, maximum length is 128. * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable> createWithServiceResponseAsync(String faceListId, String name, String userData) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> createWithServiceResponseAsync(String faceListId, String name, String userData, RecognitionModel recognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); } - NameAndUserDataContract bodyParameter = new NameAndUserDataContract(); - bodyParameter.withName(name); - bodyParameter.withUserData(userData); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.create(faceListId, this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + MetaDataContract body = new MetaDataContract(); + body.withName(name); + body.withUserData(userData); + body.withRecognitionModel(recognitionModel); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(faceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -212,96 +329,114 @@ private ServiceResponse createDelegate(Response response) th .build(response); } - @Override - public FaceListsCreateParameters create() { - return new FaceListsCreateParameters(this); + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @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 FaceList object if successful. + */ + public FaceList get(String faceListId) { + return getWithServiceResponseAsync(faceListId).toBlocking().single().body(); } /** - * Internal class implementing FaceListsCreateDefinition. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object */ - class FaceListsCreateParameters implements FaceListsCreateDefinition { - private FaceListsImpl parent; - private String faceListId; - private String name; - private String userData; - - /** - * Constructor. - * @param parent the parent object. - */ - FaceListsCreateParameters(FaceListsImpl parent) { - this.parent = parent; - } + public ServiceFuture getAsync(String faceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(faceListId), serviceCallback); + } - @Override - public FaceListsCreateParameters withFaceListId(String faceListId) { - this.faceListId = faceListId; - return this; - } + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the FaceList object + */ + public Observable getAsync(String faceListId) { + return getWithServiceResponseAsync(faceListId).map(new Func1, FaceList>() { + @Override + public FaceList call(ServiceResponse response) { + return response.body(); + } + }); + } - @Override - public FaceListsCreateParameters withName(String name) { - this.name = name; - return this; + /** + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. + * + * @param faceListId Id referencing a particular face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the FaceList object + */ + public Observable> getWithServiceResponseAsync(String faceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } - - @Override - public FaceListsCreateParameters withUserData(String userData) { - this.userData = userData; - return this; + if (faceListId == null) { + throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); } - - @Override - public void execute() { - createWithServiceResponseAsync(faceListId, name, userData).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return createWithServiceResponseAsync(faceListId, name, userData).map(new Func1, Void>() { + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(faceListId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { @Override - public Void call(ServiceResponse response) { - return response.body(); + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } } }); - } } /** - * Retrieve a face list's information. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. * * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @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 FaceList object if successful. */ - public FaceList get(String faceListId) { - return getWithServiceResponseAsync(faceListId).toBlocking().single().body(); + public FaceList get(String faceListId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(faceListId, returnRecognitionModel).toBlocking().single().body(); } /** - * Retrieve a face list's information. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. * * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture getAsync(String faceListId, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(getWithServiceResponseAsync(faceListId), serviceCallback); + public ServiceFuture getAsync(String faceListId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(faceListId, returnRecognitionModel), serviceCallback); } /** - * Retrieve a face list's information. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. * * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the FaceList object */ - public Observable getAsync(String faceListId) { - return getWithServiceResponseAsync(faceListId).map(new Func1, FaceList>() { + public Observable getAsync(String faceListId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(faceListId, returnRecognitionModel).map(new Func1, FaceList>() { @Override public FaceList call(ServiceResponse response) { return response.body(); @@ -310,21 +445,22 @@ public FaceList call(ServiceResponse response) { } /** - * Retrieve a face list's information. + * Retrieve a face list’s faceListId, name, userData, recognitionModel and faces in the face list. * * @param faceListId Id referencing a particular face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the FaceList object */ - public Observable> getWithServiceResponseAsync(String faceListId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> getWithServiceResponseAsync(String faceListId, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.get(faceListId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(faceListId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -345,43 +481,39 @@ private ServiceResponse getDelegate(Response response) t .build(response); } - /** * Update information of a face list. * * @param faceListId Id referencing a particular face list. - * @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 */ - public void update(String faceListId, UpdateFaceListsOptionalParameter updateOptionalParameter) { - updateWithServiceResponseAsync(faceListId, updateOptionalParameter).toBlocking().single().body(); + public void update(String faceListId) { + updateWithServiceResponseAsync(faceListId).toBlocking().single().body(); } /** * Update information of a face list. * * @param faceListId Id referencing a particular face list. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture updateAsync(String faceListId, UpdateFaceListsOptionalParameter updateOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(updateWithServiceResponseAsync(faceListId, updateOptionalParameter), serviceCallback); + public ServiceFuture updateAsync(String faceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(faceListId), serviceCallback); } /** * Update information of a face list. * * @param faceListId Id referencing a particular face list. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable updateAsync(String faceListId, UpdateFaceListsOptionalParameter updateOptionalParameter) { - return updateWithServiceResponseAsync(faceListId, updateOptionalParameter).map(new Func1, Void>() { + public Observable updateAsync(String faceListId) { + return updateWithServiceResponseAsync(faceListId).map(new Func1, Void>() { @Override public Void call(ServiceResponse response) { return response.body(); @@ -393,21 +525,80 @@ public Void call(ServiceResponse response) { * Update information of a face list. * * @param faceListId Id referencing a particular face list. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable> updateWithServiceResponseAsync(String faceListId, UpdateFaceListsOptionalParameter updateOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> updateWithServiceResponseAsync(String faceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); } - final String name = updateOptionalParameter != null ? updateOptionalParameter.name() : null; - final String userData = updateOptionalParameter != null ? updateOptionalParameter.userData() : null; + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(faceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 + */ + public void update(String faceListId, String name, String userData) { + updateWithServiceResponseAsync(faceListId, name, userData).toBlocking().single().body(); + } - return updateWithServiceResponseAsync(faceListId, name, userData); + /** + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String faceListId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(faceListId, name, userData), serviceCallback); + } + + /** + * Update information of a face list. + * + * @param faceListId Id referencing a particular face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String faceListId, String name, String userData) { + return updateWithServiceResponseAsync(faceListId, name, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); } /** @@ -420,17 +611,17 @@ public Observable> updateWithServiceResponseAsync(String f * @return the {@link ServiceResponse} object if successful. */ public Observable> updateWithServiceResponseAsync(String faceListId, String name, String userData) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); } - NameAndUserDataContract bodyParameter = new NameAndUserDataContract(); - bodyParameter.withName(name); - bodyParameter.withUserData(userData); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.update(faceListId, this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(faceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -451,64 +642,8 @@ private ServiceResponse updateDelegate(Response response) th .build(response); } - @Override - public FaceListsUpdateParameters update() { - return new FaceListsUpdateParameters(this); - } - /** - * Internal class implementing FaceListsUpdateDefinition. - */ - class FaceListsUpdateParameters implements FaceListsUpdateDefinition { - private FaceListsImpl parent; - private String faceListId; - private String name; - private String userData; - - /** - * Constructor. - * @param parent the parent object. - */ - FaceListsUpdateParameters(FaceListsImpl parent) { - this.parent = parent; - } - - @Override - public FaceListsUpdateParameters withFaceListId(String faceListId) { - this.faceListId = faceListId; - return this; - } - - @Override - public FaceListsUpdateParameters withName(String name) { - this.name = name; - return this; - } - - @Override - public FaceListsUpdateParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public void execute() { - updateWithServiceResponseAsync(faceListId, name, userData).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return updateWithServiceResponseAsync(faceListId, name, userData).map(new Func1, Void>() { - @Override - public Void call(ServiceResponse response) { - return response.body(); - } - }); - } - } - - /** - * Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted. + * Delete a specified face list. * * @param faceListId Id referencing a particular face list. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -520,7 +655,7 @@ public void delete(String faceListId) { } /** - * Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted. + * Delete a specified face list. * * @param faceListId Id referencing a particular face list. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. @@ -532,7 +667,7 @@ public ServiceFuture deleteAsync(String faceListId, final ServiceCallback< } /** - * Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted. + * Delete a specified face list. * * @param faceListId Id referencing a particular face list. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -548,20 +683,20 @@ public Void call(ServiceResponse response) { } /** - * Delete an existing face list according to faceListId. Persisted face images in the face list will also be deleted. + * Delete a specified face list. * * @param faceListId Id referencing a particular face list. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ public Observable> deleteWithServiceResponseAsync(String faceListId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.delete(faceListId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -584,7 +719,8 @@ private ServiceResponse deleteDelegate(Response response) th } /** - * Retrieve information about all existing face lists. Only faceListId, name and userData will be returned. + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). * * @throws IllegalArgumentException thrown if parameters fail the validation * @throws APIErrorException thrown if the request is rejected by server @@ -596,7 +732,8 @@ public List list() { } /** - * Retrieve information about all existing face lists. Only faceListId, name and userData will be returned. + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). * * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -607,7 +744,8 @@ public ServiceFuture> listAsync(final ServiceCallback call(ServiceResponse> response) { } /** - * Retrieve information about all existing face lists. Only faceListId, name and userData will be returned. + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). * * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<FaceList> object */ public Observable>> listWithServiceResponseAsync() { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<FaceList> object if successful. + */ + public List list(Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(returnRecognitionModel).toBlocking().single().body(); + } + + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(Boolean returnRecognitionModel, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(returnRecognitionModel), serviceCallback); + } + + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<FaceList> object + */ + public Observable> listAsync(Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(returnRecognitionModel).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List face lists’ faceListId, name, userData and recognitionModel. <br /> + To get face information inside faceList use [FaceList - Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c). + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<FaceList> object + */ + public Observable>> listWithServiceResponseAsync(Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.list(this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>>() { @Override public Observable>> call(Response response) { @@ -654,7 +865,8 @@ private ServiceResponse> listDelegate(Response resp } /** - * Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). Persisted image related to the face will also be deleted. + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. @@ -667,7 +879,8 @@ public void deleteFace(String faceListId, UUID persistedFaceId) { } /** - * Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). Persisted image related to the face will also be deleted. + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. @@ -680,7 +893,8 @@ public ServiceFuture deleteFaceAsync(String faceListId, UUID persistedFace } /** - * Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). Persisted image related to the face will also be deleted. + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. @@ -697,7 +911,8 @@ public Void call(ServiceResponse response) { } /** - * Delete an existing face from a face list (given by a persisitedFaceId and a faceListId). Persisted image related to the face will also be deleted. + * Delete a face from a face list by specified faceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. @@ -705,8 +920,8 @@ public Void call(ServiceResponse response) { * @return the {@link ServiceResponse} object if successful. */ public Observable> deleteFaceWithServiceResponseAsync(String faceListId, UUID persistedFaceId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); @@ -714,7 +929,7 @@ public Observable> deleteFaceWithServiceResponseAsync(Stri if (persistedFaceId == null) { throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.deleteFace(faceListId, persistedFaceId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -736,47 +951,64 @@ private ServiceResponse deleteFaceDelegate(Response response .build(response); } - /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param url Publicly reachable URL of an image - * @param addFaceFromUrlOptionalParameter 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 PersistedFace object if successful. */ - public PersistedFace addFaceFromUrl(String faceListId, String url, AddFaceFromUrlOptionalParameter addFaceFromUrlOptionalParameter) { - return addFaceFromUrlWithServiceResponseAsync(faceListId, url, addFaceFromUrlOptionalParameter).toBlocking().single().body(); + public PersistedFace addFaceFromUrl(String faceListId, String url) { + return addFaceFromUrlWithServiceResponseAsync(faceListId, url).toBlocking().single().body(); } /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param url Publicly reachable URL of an image - * @param addFaceFromUrlOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture addFaceFromUrlAsync(String faceListId, String url, AddFaceFromUrlOptionalParameter addFaceFromUrlOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(faceListId, url, addFaceFromUrlOptionalParameter), serviceCallback); + public ServiceFuture addFaceFromUrlAsync(String faceListId, String url, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(faceListId, url), serviceCallback); } /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param url Publicly reachable URL of an image - * @param addFaceFromUrlOptionalParameter 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 PersistedFace object */ - public Observable addFaceFromUrlAsync(String faceListId, String url, AddFaceFromUrlOptionalParameter addFaceFromUrlOptionalParameter) { - return addFaceFromUrlWithServiceResponseAsync(faceListId, url, addFaceFromUrlOptionalParameter).map(new Func1, PersistedFace>() { + public Observable addFaceFromUrlAsync(String faceListId, String url) { + return addFaceFromUrlWithServiceResponseAsync(faceListId, url).map(new Func1, PersistedFace>() { @Override public PersistedFace call(ServiceResponse response) { return response.body(); @@ -785,17 +1017,23 @@ public PersistedFace call(ServiceResponse response) { } /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param url Publicly reachable URL of an image - * @param addFaceFromUrlOptionalParameter 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 PersistedFace object */ - public Observable> addFaceFromUrlWithServiceResponseAsync(String faceListId, String url, AddFaceFromUrlOptionalParameter addFaceFromUrlOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> addFaceFromUrlWithServiceResponseAsync(String faceListId, String url) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); @@ -803,14 +1041,106 @@ public Observable> addFaceFromUrlWithServiceRespo if (url == null) { throw new IllegalArgumentException("Parameter url is required and cannot be null."); } - final String userData = addFaceFromUrlOptionalParameter != null ? addFaceFromUrlOptionalParameter.userData() : null; - final List targetFace = addFaceFromUrlOptionalParameter != null ? addFaceFromUrlOptionalParameter.targetFace() : null; + final String userData = null; + final List targetFace = null; + ImageUrl imageUrl = new ImageUrl(); + imageUrl.withUrl(url); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); + return service.addFaceFromUrl(faceListId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromUrlDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return addFaceFromUrlWithServiceResponseAsync(faceListId, url, userData, targetFace); + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromUrl(String faceListId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(faceListId, url, userData, targetFace).toBlocking().single().body(); } /** - * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromUrlAsync(String faceListId, String url, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(faceListId, url, userData, targetFace), serviceCallback); + } + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + * + * @param faceListId Id referencing a particular face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromUrlAsync(String faceListId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(faceListId, url, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a specified face list, up to 1,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [FaceList - Delete Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251) or [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. * * @param faceListId Id referencing a particular face list. * @param url Publicly reachable URL of an image @@ -820,8 +1150,8 @@ public Observable> addFaceFromUrlWithServiceRespo * @return the observable to the PersistedFace object */ public Observable> addFaceFromUrlWithServiceResponseAsync(String faceListId, String url, String userData, List targetFace) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); @@ -832,7 +1162,7 @@ public Observable> addFaceFromUrlWithServiceRespo Validator.validate(targetFace); ImageUrl imageUrl = new ImageUrl(); imageUrl.withUrl(url); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); return service.addFaceFromUrl(faceListId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @@ -855,83 +1185,18 @@ private ServiceResponse addFaceFromUrlDelegate(Response targetFace; - - /** - * Constructor. - * @param parent the parent object. - */ - FaceListsAddFaceFromUrlParameters(FaceListsImpl parent) { - this.parent = parent; - } - - @Override - public FaceListsAddFaceFromUrlParameters withFaceListId(String faceListId) { - this.faceListId = faceListId; - return this; - } - - @Override - public FaceListsAddFaceFromUrlParameters withUrl(String url) { - this.url = url; - return this; - } - - @Override - public FaceListsAddFaceFromUrlParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public FaceListsAddFaceFromUrlParameters withTargetFace(List targetFace) { - this.targetFace = targetFace; - return this; - } - - @Override - public PersistedFace execute() { - return addFaceFromUrlWithServiceResponseAsync(faceListId, url, userData, targetFace).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return addFaceFromUrlWithServiceResponseAsync(faceListId, url, userData, targetFace).map(new Func1, PersistedFace>() { - @Override - public PersistedFace call(ServiceResponse response) { - return response.body(); - } - }); - } - } - - /** * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. * * @param faceListId Id referencing a particular face list. * @param image An image stream. - * @param addFaceFromStreamOptionalParameter 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 PersistedFace object if successful. */ - public PersistedFace addFaceFromStream(String faceListId, byte[] image, AddFaceFromStreamOptionalParameter addFaceFromStreamOptionalParameter) { - return addFaceFromStreamWithServiceResponseAsync(faceListId, image, addFaceFromStreamOptionalParameter).toBlocking().single().body(); + public PersistedFace addFaceFromStream(String faceListId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(faceListId, image).toBlocking().single().body(); } /** @@ -939,13 +1204,12 @@ public PersistedFace addFaceFromStream(String faceListId, byte[] image, AddFaceF * * @param faceListId Id referencing a particular face list. * @param image An image stream. - * @param addFaceFromStreamOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture addFaceFromStreamAsync(String faceListId, byte[] image, AddFaceFromStreamOptionalParameter addFaceFromStreamOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(faceListId, image, addFaceFromStreamOptionalParameter), serviceCallback); + public ServiceFuture addFaceFromStreamAsync(String faceListId, byte[] image, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(faceListId, image), serviceCallback); } /** @@ -953,12 +1217,11 @@ public ServiceFuture addFaceFromStreamAsync(String faceListId, by * * @param faceListId Id referencing a particular face list. * @param image An image stream. - * @param addFaceFromStreamOptionalParameter 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 PersistedFace object */ - public Observable addFaceFromStreamAsync(String faceListId, byte[] image, AddFaceFromStreamOptionalParameter addFaceFromStreamOptionalParameter) { - return addFaceFromStreamWithServiceResponseAsync(faceListId, image, addFaceFromStreamOptionalParameter).map(new Func1, PersistedFace>() { + public Observable addFaceFromStreamAsync(String faceListId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(faceListId, image).map(new Func1, PersistedFace>() { @Override public PersistedFace call(ServiceResponse response) { return response.body(); @@ -971,13 +1234,12 @@ public PersistedFace call(ServiceResponse response) { * * @param faceListId Id referencing a particular face list. * @param image An image stream. - * @param addFaceFromStreamOptionalParameter 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 PersistedFace object */ - public Observable> addFaceFromStreamWithServiceResponseAsync(String faceListId, byte[] image, AddFaceFromStreamOptionalParameter addFaceFromStreamOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> addFaceFromStreamWithServiceResponseAsync(String faceListId, byte[] image) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); @@ -985,10 +1247,72 @@ public Observable> addFaceFromStreamWithServiceRe if (image == null) { throw new IllegalArgumentException("Parameter image is required and cannot be null."); } - final String userData = addFaceFromStreamOptionalParameter != null ? addFaceFromStreamOptionalParameter.userData() : null; - final List targetFace = addFaceFromStreamOptionalParameter != null ? addFaceFromStreamOptionalParameter.targetFace() : null; + final String userData = null; + final List targetFace = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.addFaceFromStream(faceListId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromStreamDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return addFaceFromStreamWithServiceResponseAsync(faceListId, image, userData, targetFace); + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromStream(String faceListId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(faceListId, image, userData, targetFace).toBlocking().single().body(); + } + + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromStreamAsync(String faceListId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(faceListId, image, userData, targetFace), serviceCallback); + } + + /** + * Add a face to a face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param faceListId Id referencing a particular face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromStreamAsync(String faceListId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(faceListId, image, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); } /** @@ -1002,8 +1326,8 @@ public Observable> addFaceFromStreamWithServiceRe * @return the observable to the PersistedFace object */ public Observable> addFaceFromStreamWithServiceResponseAsync(String faceListId, byte[] image, String userData, List targetFace) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceListId == null) { throw new IllegalArgumentException("Parameter faceListId is required and cannot be null."); @@ -1012,9 +1336,8 @@ public Observable> addFaceFromStreamWithServiceRe throw new IllegalArgumentException("Parameter image is required and cannot be null."); } Validator.validate(targetFace); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); - RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); return service.addFaceFromStream(faceListId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -1036,67 +1359,4 @@ private ServiceResponse addFaceFromStreamDelegate(Response targetFace; - - /** - * Constructor. - * @param parent the parent object. - */ - FaceListsAddFaceFromStreamParameters(FaceListsImpl parent) { - this.parent = parent; - } - - @Override - public FaceListsAddFaceFromStreamParameters withFaceListId(String faceListId) { - this.faceListId = faceListId; - return this; - } - - @Override - public FaceListsAddFaceFromStreamParameters withImage(byte[] image) { - this.image = image; - return this; - } - - @Override - public FaceListsAddFaceFromStreamParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public FaceListsAddFaceFromStreamParameters withTargetFace(List targetFace) { - this.targetFace = targetFace; - return this; - } - - @Override - public PersistedFace execute() { - return addFaceFromStreamWithServiceResponseAsync(faceListId, image, userData, targetFace).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return addFaceFromStreamWithServiceResponseAsync(faceListId, image, userData, targetFace).map(new Func1, PersistedFace>() { - @Override - public PersistedFace call(ServiceResponse response) { - return response.body(); - } - }); - } - } - } diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FacesImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FacesImpl.java index 15f568d59a33..159c685cba5c 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FacesImpl.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/FacesImpl.java @@ -8,10 +8,6 @@ package com.microsoft.azure.cognitiveservices.vision.faceapi.implementation; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.FindSimilarOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.IdentifyOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.DetectWithUrlOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.DetectWithStreamOptionalParameter; import retrofit2.Retrofit; import com.microsoft.azure.cognitiveservices.vision.faceapi.Faces; import com.google.common.base.Joiner; @@ -26,6 +22,7 @@ import com.microsoft.azure.cognitiveservices.vision.faceapi.models.IdentifyRequest; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.IdentifyResult; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ImageUrl; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SimilarFace; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.VerifyFaceToFaceRequest; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.VerifyFaceToPersonRequest; @@ -35,6 +32,7 @@ import com.microsoft.rest.ServiceFuture; import com.microsoft.rest.ServiceResponse; import com.microsoft.rest.Validator; +import java.io.InputStream; import java.io.IOException; import java.util.List; import java.util.UUID; @@ -58,7 +56,7 @@ public class FacesImpl implements Faces { /** The Retrofit service to perform REST calls. */ private FacesService service; /** The service client containing this operation class. */ - private FaceAPIImpl client; + private FaceClientImpl client; /** * Initializes an instance of FacesImpl. @@ -66,7 +64,7 @@ public class FacesImpl implements Faces { * @param retrofit the Retrofit instance built from a Retrofit Builder. * @param client the instance of the service client containing this operation class. */ - public FacesImpl(Retrofit retrofit, FaceAPIImpl client) { + public FacesImpl(Retrofit retrofit, FaceClientImpl client) { this.service = retrofit.create(FacesService.class); this.client = client; } @@ -78,72 +76,74 @@ public FacesImpl(Retrofit retrofit, FaceAPIImpl client) { interface FacesService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Faces findSimilar" }) @POST("findsimilars") - Observable> findSimilar(@Header("accept-language") String acceptLanguage, @Body FindSimilarRequest bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> findSimilar(@Header("accept-language") String acceptLanguage, @Body FindSimilarRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Faces group" }) @POST("group") - Observable> group(@Header("accept-language") String acceptLanguage, @Body GroupRequest bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> group(@Header("accept-language") String acceptLanguage, @Body GroupRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Faces identify" }) @POST("identify") - Observable> identify(@Header("accept-language") String acceptLanguage, @Body IdentifyRequest bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> identify(@Header("accept-language") String acceptLanguage, @Body IdentifyRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Faces verifyFaceToFace" }) @POST("verify") - Observable> verifyFaceToFace(@Header("accept-language") String acceptLanguage, @Body VerifyFaceToFaceRequest bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> verifyFaceToFace(@Header("accept-language") String acceptLanguage, @Body VerifyFaceToFaceRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Faces detectWithUrl" }) @POST("detect") - Observable> detectWithUrl(@Query("returnFaceId") Boolean returnFaceId, @Query("returnFaceLandmarks") Boolean returnFaceLandmarks, @Query("returnFaceAttributes") String returnFaceAttributes, @Header("accept-language") String acceptLanguage, @Body ImageUrl imageUrl, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> detectWithUrl(@Query("returnFaceId") Boolean returnFaceId, @Query("returnFaceLandmarks") Boolean returnFaceLandmarks, @Query("returnFaceAttributes") String returnFaceAttributes, @Query("recognitionModel") RecognitionModel recognitionModel1, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Body ImageUrl imageUrl, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Faces verifyFaceToPerson" }) @POST("verify") - Observable> verifyFaceToPerson(@Header("accept-language") String acceptLanguage, @Body VerifyFaceToPersonRequest bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> verifyFaceToPerson(@Header("accept-language") String acceptLanguage, @Body VerifyFaceToPersonRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/octet-stream", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Faces detectWithStream" }) @POST("detect") - Observable> detectWithStream(@Query("returnFaceId") Boolean returnFaceId, @Query("returnFaceLandmarks") Boolean returnFaceLandmarks, @Query("returnFaceAttributes") String returnFaceAttributes, @Body RequestBody image, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> detectWithStream(@Query("returnFaceId") Boolean returnFaceId, @Query("returnFaceLandmarks") Boolean returnFaceLandmarks, @Query("returnFaceAttributes") String returnFaceAttributes, @Body RequestBody image, @Query("recognitionModel") RecognitionModel recognitionModel1, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); } - /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. * * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call - * @param findSimilarOptionalParameter 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<SimilarFace> object if successful. */ - public List findSimilar(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter) { - return findSimilarWithServiceResponseAsync(faceId, findSimilarOptionalParameter).toBlocking().single().body(); + public List findSimilar(UUID faceId) { + return findSimilarWithServiceResponseAsync(faceId).toBlocking().single().body(); } /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. * * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call - * @param findSimilarOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture> findSimilarAsync(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter, final ServiceCallback> serviceCallback) { - return ServiceFuture.fromResponse(findSimilarWithServiceResponseAsync(faceId, findSimilarOptionalParameter), serviceCallback); + public ServiceFuture> findSimilarAsync(UUID faceId, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(findSimilarWithServiceResponseAsync(faceId), serviceCallback); } /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. * * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call - * @param findSimilarOptionalParameter 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<SimilarFace> object */ - public Observable> findSimilarAsync(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter) { - return findSimilarWithServiceResponseAsync(faceId, findSimilarOptionalParameter).map(new Func1>, List>() { + public Observable> findSimilarAsync(UUID faceId) { + return findSimilarWithServiceResponseAsync(faceId).map(new Func1>, List>() { @Override public List call(ServiceResponse> response) { return response.body(); @@ -152,55 +152,141 @@ public List call(ServiceResponse> response) { } /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. * * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call - * @param findSimilarOptionalParameter 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<SimilarFace> object */ - public Observable>> findSimilarWithServiceResponseAsync(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable>> findSimilarWithServiceResponseAsync(UUID faceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceId == null) { throw new IllegalArgumentException("Parameter faceId is required and cannot be null."); } - final String faceListId = findSimilarOptionalParameter != null ? findSimilarOptionalParameter.faceListId() : null; - final List faceIds = findSimilarOptionalParameter != null ? findSimilarOptionalParameter.faceIds() : null; - final Integer maxNumOfCandidatesReturned = findSimilarOptionalParameter != null ? findSimilarOptionalParameter.maxNumOfCandidatesReturned() : null; - final FindSimilarMatchMode mode = findSimilarOptionalParameter != null ? findSimilarOptionalParameter.mode() : null; + final String faceListId = null; + final String largeFaceListId = null; + final List faceIds = null; + final Integer maxNumOfCandidatesReturned = null; + final FindSimilarMatchMode mode = null; + FindSimilarRequest body = new FindSimilarRequest(); + body.withFaceId(faceId); + body.withFaceListId(null); + body.withLargeFaceListId(null); + body.withFaceIds(null); + body.withMaxNumOfCandidatesReturned(null); + body.withMode(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.findSimilar(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = findSimilarDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return findSimilarWithServiceResponseAsync(faceId, faceListId, faceIds, maxNumOfCandidatesReturned, mode); + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. + * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' + * @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<SimilarFace> object if successful. + */ + public List findSimilar(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode) { + return findSimilarWithServiceResponseAsync(faceId, faceListId, largeFaceListId, faceIds, maxNumOfCandidatesReturned, mode).toBlocking().single().body(); } /** - * Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId. + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. * * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call - * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId and faceIds should not be provided at the same time - * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. + * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> findSimilarAsync(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(findSimilarWithServiceResponseAsync(faceId, faceListId, largeFaceListId, faceIds, maxNumOfCandidatesReturned, mode), serviceCallback); + } + + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<SimilarFace> object */ - public Observable>> findSimilarWithServiceResponseAsync(UUID faceId, String faceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> findSimilarAsync(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode) { + return findSimilarWithServiceResponseAsync(faceId, faceListId, largeFaceListId, faceIds, maxNumOfCandidatesReturned, mode).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * Given query face's faceId, to search the similar-looking faces from a faceId array, a face list or a large face list. faceId array contains the faces created by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), which will expire 24 hours after creation. A "faceListId" is created by [FaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) containing persistedFaceIds that will not expire. And a "largeFaceListId" is created by [LargeFaceList - Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) containing persistedFaceIds that will also not expire. Depending on the input the returned similar faces list contains faceIds or persistedFaceIds ranked by similarity. + <br/>Find similar has two working modes, "matchPerson" and "matchFace". "matchPerson" is the default mode that it tries to find faces of the same person as possible by using internal same-person thresholds. It is useful to find a known person's other photos. Note that an empty list will be returned if no faces pass the internal thresholds. "matchFace" mode ignores same-person thresholds and returns ranked similar faces anyway, even the similarity is low. It can be used in the cases like searching celebrity-looking faces. + <br/>The 'recognitionModel' associated with the query face's faceId should be the same as the 'recognitionModel' used by the target faceId array, face list or large face list. + * + * @param faceId FaceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call + * @param faceListId An existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param largeFaceListId An existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param faceIds An array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * @param maxNumOfCandidatesReturned The number of top similar faces returned. The valid range is [1, 1000]. + * @param mode Similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<SimilarFace> object + */ + public Observable>> findSimilarWithServiceResponseAsync(UUID faceId, String faceListId, String largeFaceListId, List faceIds, Integer maxNumOfCandidatesReturned, FindSimilarMatchMode mode) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceId == null) { throw new IllegalArgumentException("Parameter faceId is required and cannot be null."); } Validator.validate(faceIds); - FindSimilarRequest bodyParameter = new FindSimilarRequest(); - bodyParameter.withFaceId(faceId); - bodyParameter.withFaceListId(faceListId); - bodyParameter.withFaceIds(faceIds); - bodyParameter.withMaxNumOfCandidatesReturned(maxNumOfCandidatesReturned); - bodyParameter.withMode(mode); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.findSimilar(this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + FindSimilarRequest body = new FindSimilarRequest(); + body.withFaceId(faceId); + body.withFaceListId(faceListId); + body.withLargeFaceListId(largeFaceListId); + body.withFaceIds(faceIds); + body.withMaxNumOfCandidatesReturned(maxNumOfCandidatesReturned); + body.withMode(mode); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.findSimilar(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>>() { @Override public Observable>> call(Response response) { @@ -221,78 +307,12 @@ private ServiceResponse> findSimilarDelegate(Response faceIds; - private Integer maxNumOfCandidatesReturned; - private FindSimilarMatchMode mode; - - /** - * Constructor. - * @param parent the parent object. - */ - FacesFindSimilarParameters(FacesImpl parent) { - this.parent = parent; - } - - @Override - public FacesFindSimilarParameters withFaceId(UUID faceId) { - this.faceId = faceId; - return this; - } - - @Override - public FacesFindSimilarParameters withFaceListId(String faceListId) { - this.faceListId = faceListId; - return this; - } - - @Override - public FacesFindSimilarParameters withFaceIds(List faceIds) { - this.faceIds = faceIds; - return this; - } - - @Override - public FacesFindSimilarParameters withMaxNumOfCandidatesReturned(Integer maxNumOfCandidatesReturned) { - this.maxNumOfCandidatesReturned = maxNumOfCandidatesReturned; - return this; - } - - @Override - public FacesFindSimilarParameters withMode(FindSimilarMatchMode mode) { - this.mode = mode; - return this; - } - - @Override - public List execute() { - return findSimilarWithServiceResponseAsync(faceId, faceListId, faceIds, maxNumOfCandidatesReturned, mode).toBlocking().single().body(); - } - - @Override - public Observable> executeAsync() { - return findSimilarWithServiceResponseAsync(faceId, faceListId, faceIds, maxNumOfCandidatesReturned, mode).map(new Func1>, List>() { - @Override - public List call(ServiceResponse> response) { - return response.body(); - } - }); - } - } - /** - * Divide candidate faces into groups based on face similarity. + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. * * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces * @throws IllegalArgumentException thrown if parameters fail the validation @@ -305,7 +325,11 @@ public GroupResult group(List faceIds) { } /** - * Divide candidate faces into groups based on face similarity. + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. * * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces * @param serviceCallback the async ServiceCallback to handle successful and failed responses. @@ -317,7 +341,11 @@ public ServiceFuture groupAsync(List faceIds, final ServiceCa } /** - * Divide candidate faces into groups based on face similarity. + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. * * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces * @throws IllegalArgumentException thrown if parameters fail the validation @@ -333,24 +361,28 @@ public GroupResult call(ServiceResponse response) { } /** - * Divide candidate faces into groups based on face similarity. + * Divide candidate faces into groups based on face similarity.<br /> + * The output is one or more disjointed face groups and a messyGroup. A face group contains faces that have similar looking, often of the same person. Face groups are ranked by group size, i.e. number of faces. Notice that faces belonging to a same person might be split into several groups in the result. + * MessyGroup is a special face group containing faces that cannot find any similar counterpart face from original faces. The messyGroup will not appear in the result if all faces found their counterparts. + * Group API needs at least 2 candidate faces and 1000 at most. We suggest to try [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) when you only have 2 candidate faces. + * The 'recognitionModel' associated with the query faces' faceIds should be the same. * * @param faceIds Array of candidate faceId created by Face - Detect. The maximum is 1000 faces * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the GroupResult object */ public Observable> groupWithServiceResponseAsync(List faceIds) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceIds == null) { throw new IllegalArgumentException("Parameter faceIds is required and cannot be null."); } Validator.validate(faceIds); - GroupRequest bodyParameter = new GroupRequest(); - bodyParameter.withFaceIds(faceIds); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.group(this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + GroupRequest body = new GroupRequest(); + body.withFaceIds(faceIds); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.group(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -371,47 +403,67 @@ private ServiceResponse groupDelegate(Response respon .build(response); } - /** - * Identify unknown faces from a person group. + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. * - * @param personGroupId PersonGroupId of the target person group, created by PersonGroups.Create * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. - * @param identifyOptionalParameter 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<IdentifyResult> object if successful. */ - public List identify(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter) { - return identifyWithServiceResponseAsync(personGroupId, faceIds, identifyOptionalParameter).toBlocking().single().body(); + public List identify(List faceIds) { + return identifyWithServiceResponseAsync(faceIds).toBlocking().single().body(); } /** - * Identify unknown faces from a person group. + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. * - * @param personGroupId PersonGroupId of the target person group, created by PersonGroups.Create * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. - * @param identifyOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture> identifyAsync(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter, final ServiceCallback> serviceCallback) { - return ServiceFuture.fromResponse(identifyWithServiceResponseAsync(personGroupId, faceIds, identifyOptionalParameter), serviceCallback); + public ServiceFuture> identifyAsync(List faceIds, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(identifyWithServiceResponseAsync(faceIds), serviceCallback); } /** - * Identify unknown faces from a person group. + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. * - * @param personGroupId PersonGroupId of the target person group, created by PersonGroups.Create * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. - * @param identifyOptionalParameter 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<IdentifyResult> object */ - public Observable> identifyAsync(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter) { - return identifyWithServiceResponseAsync(personGroupId, faceIds, identifyOptionalParameter).map(new Func1>, List>() { + public Observable> identifyAsync(List faceIds) { + return identifyWithServiceResponseAsync(faceIds).map(new Func1>, List>() { @Override public List call(ServiceResponse> response) { return response.body(); @@ -420,59 +472,170 @@ public List call(ServiceResponse> response) } /** - * Identify unknown faces from a person group. + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. * - * @param personGroupId PersonGroupId of the target person group, created by PersonGroups.Create * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. - * @param identifyOptionalParameter 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<IdentifyResult> object */ - public Observable>> identifyWithServiceResponseAsync(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); - } - if (personGroupId == null) { - throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); + public Observable>> identifyWithServiceResponseAsync(List faceIds) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceIds == null) { throw new IllegalArgumentException("Parameter faceIds is required and cannot be null."); } Validator.validate(faceIds); - final Integer maxNumOfCandidatesReturned = identifyOptionalParameter != null ? identifyOptionalParameter.maxNumOfCandidatesReturned() : null; - final Double confidenceThreshold = identifyOptionalParameter != null ? identifyOptionalParameter.confidenceThreshold() : null; + final String personGroupId = null; + final String largePersonGroupId = null; + final Integer maxNumOfCandidatesReturned = null; + final Double confidenceThreshold = null; + IdentifyRequest body = new IdentifyRequest(); + body.withFaceIds(faceIds); + body.withPersonGroupId(null); + body.withLargePersonGroupId(null); + body.withMaxNumOfCandidatesReturned(null); + body.withConfidenceThreshold(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.identify(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = identifyDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). + * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). + * @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<IdentifyResult> object if successful. + */ + public List identify(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold) { + return identifyWithServiceResponseAsync(faceIds, personGroupId, largePersonGroupId, maxNumOfCandidatesReturned, confidenceThreshold).toBlocking().single().body(); + } + + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). + * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> identifyAsync(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(identifyWithServiceResponseAsync(faceIds, personGroupId, largePersonGroupId, maxNumOfCandidatesReturned, confidenceThreshold), serviceCallback); + } - return identifyWithServiceResponseAsync(personGroupId, faceIds, maxNumOfCandidatesReturned, confidenceThreshold); + /** + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. + * + * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). + * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<IdentifyResult> object + */ + public Observable> identifyAsync(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold) { + return identifyWithServiceResponseAsync(faceIds, personGroupId, largePersonGroupId, maxNumOfCandidatesReturned, confidenceThreshold).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); } /** - * Identify unknown faces from a person group. + * 1-to-many identification to find the closest matches of the specific query person face from a person group or large person group. + <br/> For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s) for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for identification. See more in [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) and [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + <br/> + Remarks:<br /> + * The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces. + * Each person in the person group/large person group could have more than one face, but no more than 248 faces. + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array. + * Try [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) when you need to find similar faces from a face list/large face list instead of a person group/large person group. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group. * - * @param personGroupId PersonGroupId of the target person group, created by PersonGroups.Create * @param faceIds Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * @param personGroupId PersonGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId LargePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * @param maxNumOfCandidatesReturned The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). * @param confidenceThreshold Confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<IdentifyResult> object */ - public Observable>> identifyWithServiceResponseAsync(String personGroupId, List faceIds, Integer maxNumOfCandidatesReturned, Double confidenceThreshold) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); - } - if (personGroupId == null) { - throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); + public Observable>> identifyWithServiceResponseAsync(List faceIds, String personGroupId, String largePersonGroupId, Integer maxNumOfCandidatesReturned, Double confidenceThreshold) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceIds == null) { throw new IllegalArgumentException("Parameter faceIds is required and cannot be null."); } Validator.validate(faceIds); - IdentifyRequest bodyParameter = new IdentifyRequest(); - bodyParameter.withPersonGroupId(personGroupId); - bodyParameter.withFaceIds(faceIds); - bodyParameter.withMaxNumOfCandidatesReturned(maxNumOfCandidatesReturned); - bodyParameter.withConfidenceThreshold(confidenceThreshold); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.identify(this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + IdentifyRequest body = new IdentifyRequest(); + body.withFaceIds(faceIds); + body.withPersonGroupId(personGroupId); + body.withLargePersonGroupId(largePersonGroupId); + body.withMaxNumOfCandidatesReturned(maxNumOfCandidatesReturned); + body.withConfidenceThreshold(confidenceThreshold); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.identify(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>>() { @Override public Observable>> call(Response response) { @@ -493,71 +656,13 @@ private ServiceResponse> identifyDelegate(Response faceIds; - private Integer maxNumOfCandidatesReturned; - private Double confidenceThreshold; - - /** - * Constructor. - * @param parent the parent object. - */ - FacesIdentifyParameters(FacesImpl parent) { - this.parent = parent; - } - - @Override - public FacesIdentifyParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public FacesIdentifyParameters withFaceIds(List faceIds) { - this.faceIds = faceIds; - return this; - } - - @Override - public FacesIdentifyParameters withMaxNumOfCandidatesReturned(Integer maxNumOfCandidatesReturned) { - this.maxNumOfCandidatesReturned = maxNumOfCandidatesReturned; - return this; - } - - @Override - public FacesIdentifyParameters withConfidenceThreshold(Double confidenceThreshold) { - this.confidenceThreshold = confidenceThreshold; - return this; - } - - @Override - public List execute() { - return identifyWithServiceResponseAsync(personGroupId, faceIds, maxNumOfCandidatesReturned, confidenceThreshold).toBlocking().single().body(); - } - - @Override - public Observable> executeAsync() { - return identifyWithServiceResponseAsync(personGroupId, faceIds, maxNumOfCandidatesReturned, confidenceThreshold).map(new Func1>, List>() { - @Override - public List call(ServiceResponse> response) { - return response.body(); - } - }); - } - } - /** * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. * * @param faceId1 FaceId of the first face, comes from Face - Detect * @param faceId2 FaceId of the second face, comes from Face - Detect @@ -572,6 +677,11 @@ public VerifyResult verifyFaceToFace(UUID faceId1, UUID faceId2) { /** * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. * * @param faceId1 FaceId of the first face, comes from Face - Detect * @param faceId2 FaceId of the second face, comes from Face - Detect @@ -585,6 +695,11 @@ public ServiceFuture verifyFaceToFaceAsync(UUID faceId1, UUID face /** * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. * * @param faceId1 FaceId of the first face, comes from Face - Detect * @param faceId2 FaceId of the second face, comes from Face - Detect @@ -602,6 +717,11 @@ public VerifyResult call(ServiceResponse response) { /** * Verify whether two faces belong to a same person or whether one face belongs to a person. + <br/> + Remarks:<br /> + * Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * For the scenarios that are sensitive to accuracy please make your own judgment. + * The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target face, person group or large person group. * * @param faceId1 FaceId of the first face, comes from Face - Detect * @param faceId2 FaceId of the second face, comes from Face - Detect @@ -609,8 +729,8 @@ public VerifyResult call(ServiceResponse response) { * @return the observable to the VerifyResult object */ public Observable> verifyFaceToFaceWithServiceResponseAsync(UUID faceId1, UUID faceId2) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceId1 == null) { throw new IllegalArgumentException("Parameter faceId1 is required and cannot be null."); @@ -618,11 +738,11 @@ public Observable> verifyFaceToFaceWithServiceResp if (faceId2 == null) { throw new IllegalArgumentException("Parameter faceId2 is required and cannot be null."); } - VerifyFaceToFaceRequest bodyParameter = new VerifyFaceToFaceRequest(); - bodyParameter.withFaceId1(faceId1); - bodyParameter.withFaceId2(faceId2); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.verifyFaceToFace(this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + VerifyFaceToFaceRequest body = new VerifyFaceToFaceRequest(); + body.withFaceId1(faceId1); + body.withFaceId2(faceId2); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.verifyFaceToFace(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -643,44 +763,67 @@ private ServiceResponse verifyFaceToFaceDelegate(Response detectWithUrl(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter) { - return detectWithUrlWithServiceResponseAsync(url, detectWithUrlOptionalParameter).toBlocking().single().body(); + public List detectWithUrl(String url) { + return detectWithUrlWithServiceResponseAsync(url).toBlocking().single().body(); } /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). * * @param url Publicly reachable URL of an image - * @param detectWithUrlOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture> detectWithUrlAsync(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter, final ServiceCallback> serviceCallback) { - return ServiceFuture.fromResponse(detectWithUrlWithServiceResponseAsync(url, detectWithUrlOptionalParameter), serviceCallback); + public ServiceFuture> detectWithUrlAsync(String url, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(detectWithUrlWithServiceResponseAsync(url), serviceCallback); } /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). * * @param url Publicly reachable URL of an image - * @param detectWithUrlOptionalParameter 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<DetectedFace> object */ - public Observable> detectWithUrlAsync(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter) { - return detectWithUrlWithServiceResponseAsync(url, detectWithUrlOptionalParameter).map(new Func1>, List>() { + public Observable> detectWithUrlAsync(String url) { + return detectWithUrlWithServiceResponseAsync(url).map(new Func1>, List>() { @Override public List call(ServiceResponse> response) { return response.body(); @@ -689,40 +832,158 @@ public List call(ServiceResponse> response) { } /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). * * @param url Publicly reachable URL of an image - * @param detectWithUrlOptionalParameter 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<DetectedFace> object */ - public Observable>> detectWithUrlWithServiceResponseAsync(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable>> detectWithUrlWithServiceResponseAsync(String url) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (url == null) { throw new IllegalArgumentException("Parameter url is required and cannot be null."); } - final Boolean returnFaceId = detectWithUrlOptionalParameter != null ? detectWithUrlOptionalParameter.returnFaceId() : null; - final Boolean returnFaceLandmarks = detectWithUrlOptionalParameter != null ? detectWithUrlOptionalParameter.returnFaceLandmarks() : null; - final List returnFaceAttributes = detectWithUrlOptionalParameter != null ? detectWithUrlOptionalParameter.returnFaceAttributes() : null; + final Boolean returnFaceId = null; + final Boolean returnFaceLandmarks = null; + final List returnFaceAttributes = null; + final RecognitionModel recognitionModel = null; + final Boolean returnRecognitionModel = null; + ImageUrl imageUrl = new ImageUrl(); + imageUrl.withUrl(url); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String returnFaceAttributesConverted = this.client.serializerAdapter().serializeList(returnFaceAttributes, CollectionFormat.CSV); + return service.detectWithUrl(returnFaceId, returnFaceLandmarks, returnFaceAttributesConverted, recognitionModel, returnRecognitionModel, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = detectWithUrlDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return detectWithUrlWithServiceResponseAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes); + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<DetectedFace> object if successful. + */ + public List detectWithUrl(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel) { + return detectWithUrlWithServiceResponseAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel).toBlocking().single().body(); } /** - * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> detectWithUrlAsync(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(detectWithUrlWithServiceResponseAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel), serviceCallback); + } + + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). * * @param url Publicly reachable URL of an image * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<DetectedFace> object */ - public Observable>> detectWithUrlWithServiceResponseAsync(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> detectWithUrlAsync(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel) { + return detectWithUrlWithServiceResponseAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<br /> + * Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise. + * No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239), [Face - Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a), and [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). It will expire 24 hours after the detection call. + * Higher face image quality means better detection and recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need to detect very small but clear faces, please try to enlarge the input image. + * Up to 64 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. + * Face detector prefer frontal and near-frontal faces. There are cases that faces may not be detected, e.g. exceptionally large face angles (head-pose) or being occluded, or wrong image orientation. + * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise) may not be perfectly accurate. + * Different 'recognitionModel' values are provided. If follow-up operations like Verify, Identify, Find Similar are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [How to specify a recognition model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). + * + * @param url Publicly reachable URL of an image + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + public Observable>> detectWithUrlWithServiceResponseAsync(String url, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (url == null) { throw new IllegalArgumentException("Parameter url is required and cannot be null."); @@ -730,9 +991,9 @@ public Observable>> detectWithUrlWithServiceR Validator.validate(returnFaceAttributes); ImageUrl imageUrl = new ImageUrl(); imageUrl.withUrl(url); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); String returnFaceAttributesConverted = this.client.serializerAdapter().serializeList(returnFaceAttributes, CollectionFormat.CSV); - return service.detectWithUrl(returnFaceId, returnFaceLandmarks, returnFaceAttributesConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + return service.detectWithUrl(returnFaceId, returnFaceLandmarks, returnFaceAttributesConverted, recognitionModel, returnRecognitionModel, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>>() { @Override public Observable>> call(Response response) { @@ -753,109 +1014,133 @@ private ServiceResponse> detectWithUrlDelegate(Response returnFaceAttributes; - - /** - * Constructor. - * @param parent the parent object. - */ - FacesDetectWithUrlParameters(FacesImpl parent) { - this.parent = parent; - } + public ServiceFuture verifyFaceToPersonAsync(UUID faceId, UUID personId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(verifyFaceToPersonWithServiceResponseAsync(faceId, personId), serviceCallback); + } - @Override - public FacesDetectWithUrlParameters withUrl(String url) { - this.url = url; - return this; - } + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the VerifyResult object + */ + public Observable verifyFaceToPersonAsync(UUID faceId, UUID personId) { + return verifyFaceToPersonWithServiceResponseAsync(faceId, personId).map(new Func1, VerifyResult>() { + @Override + public VerifyResult call(ServiceResponse response) { + return response.body(); + } + }); + } - @Override - public FacesDetectWithUrlParameters withReturnFaceId(Boolean returnFaceId) { - this.returnFaceId = returnFaceId; - return this; + /** + * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. + * + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the VerifyResult object + */ + public Observable> verifyFaceToPersonWithServiceResponseAsync(UUID faceId, UUID personId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } - - @Override - public FacesDetectWithUrlParameters withReturnFaceLandmarks(Boolean returnFaceLandmarks) { - this.returnFaceLandmarks = returnFaceLandmarks; - return this; + if (faceId == null) { + throw new IllegalArgumentException("Parameter faceId is required and cannot be null."); } - - @Override - public FacesDetectWithUrlParameters withReturnFaceAttributes(List returnFaceAttributes) { - this.returnFaceAttributes = returnFaceAttributes; - return this; + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); } - - @Override - public List execute() { - return detectWithUrlWithServiceResponseAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes).toBlocking().single().body(); - } - - @Override - public Observable> executeAsync() { - return detectWithUrlWithServiceResponseAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes).map(new Func1>, List>() { + final String personGroupId = null; + final String largePersonGroupId = null; + VerifyFaceToPersonRequest body = new VerifyFaceToPersonRequest(); + body.withFaceId(faceId); + body.withPersonGroupId(null); + body.withLargePersonGroupId(null); + body.withPersonId(personId); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.verifyFaceToPerson(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { @Override - public List call(ServiceResponse> response) { - return response.body(); + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = verifyFaceToPersonDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } } }); - } } /** * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. * - * @param faceId FaceId the face, comes from Face - Detect - * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create. - * @param personId Specify a certain person in a person group. personId is created in Persons.Create. + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * @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 VerifyResult object if successful. */ - public VerifyResult verifyFaceToPerson(UUID faceId, String personGroupId, UUID personId) { - return verifyFaceToPersonWithServiceResponseAsync(faceId, personGroupId, personId).toBlocking().single().body(); + public VerifyResult verifyFaceToPerson(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId) { + return verifyFaceToPersonWithServiceResponseAsync(faceId, personId, personGroupId, largePersonGroupId).toBlocking().single().body(); } /** * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. * - * @param faceId FaceId the face, comes from Face - Detect - * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create. - * @param personId Specify a certain person in a person group. personId is created in Persons.Create. + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture verifyFaceToPersonAsync(UUID faceId, String personGroupId, UUID personId, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(verifyFaceToPersonWithServiceResponseAsync(faceId, personGroupId, personId), serviceCallback); + public ServiceFuture verifyFaceToPersonAsync(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(verifyFaceToPersonWithServiceResponseAsync(faceId, personId, personGroupId, largePersonGroupId), serviceCallback); } /** * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. * - * @param faceId FaceId the face, comes from Face - Detect - * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create. - * @param personId Specify a certain person in a person group. personId is created in Persons.Create. + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the VerifyResult object */ - public Observable verifyFaceToPersonAsync(UUID faceId, String personGroupId, UUID personId) { - return verifyFaceToPersonWithServiceResponseAsync(faceId, personGroupId, personId).map(new Func1, VerifyResult>() { + public Observable verifyFaceToPersonAsync(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId) { + return verifyFaceToPersonWithServiceResponseAsync(faceId, personId, personGroupId, largePersonGroupId).map(new Func1, VerifyResult>() { @Override public VerifyResult call(ServiceResponse response) { return response.body(); @@ -866,31 +1151,30 @@ public VerifyResult call(ServiceResponse response) { /** * Verify whether two faces belong to a same person. Compares a face Id with a Person Id. * - * @param faceId FaceId the face, comes from Face - Detect - * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create. - * @param personId Specify a certain person in a person group. personId is created in Persons.Create. + * @param faceId FaceId of the face, comes from Face - Detect + * @param personId Specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. + * @param personGroupId Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * @param largePersonGroupId Using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the VerifyResult object */ - public Observable> verifyFaceToPersonWithServiceResponseAsync(UUID faceId, String personGroupId, UUID personId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> verifyFaceToPersonWithServiceResponseAsync(UUID faceId, UUID personId, String personGroupId, String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (faceId == null) { throw new IllegalArgumentException("Parameter faceId is required and cannot be null."); } - if (personGroupId == null) { - throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); - } if (personId == null) { throw new IllegalArgumentException("Parameter personId is required and cannot be null."); } - VerifyFaceToPersonRequest bodyParameter = new VerifyFaceToPersonRequest(); - bodyParameter.withFaceId(faceId); - bodyParameter.withPersonGroupId(personGroupId); - bodyParameter.withPersonId(personId); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.verifyFaceToPerson(this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + VerifyFaceToPersonRequest body = new VerifyFaceToPersonRequest(); + body.withFaceId(faceId); + body.withPersonGroupId(personGroupId); + body.withLargePersonGroupId(largePersonGroupId); + body.withPersonId(personId); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.verifyFaceToPerson(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -911,44 +1195,40 @@ private ServiceResponse verifyFaceToPersonDelegate(Response detectWithStream(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter) { - return detectWithStreamWithServiceResponseAsync(image, detectWithStreamOptionalParameter).toBlocking().single().body(); + public List detectWithStream(byte[] image) { + return detectWithStreamWithServiceResponseAsync(image).toBlocking().single().body(); } /** * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. * * @param image An image stream. - * @param detectWithStreamOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture> detectWithStreamAsync(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter, final ServiceCallback> serviceCallback) { - return ServiceFuture.fromResponse(detectWithStreamWithServiceResponseAsync(image, detectWithStreamOptionalParameter), serviceCallback); + public ServiceFuture> detectWithStreamAsync(byte[] image, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(detectWithStreamWithServiceResponseAsync(image), serviceCallback); } /** * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. * * @param image An image stream. - * @param detectWithStreamOptionalParameter 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<DetectedFace> object */ - public Observable> detectWithStreamAsync(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter) { - return detectWithStreamWithServiceResponseAsync(image, detectWithStreamOptionalParameter).map(new Func1>, List>() { + public Observable> detectWithStreamAsync(byte[] image) { + return detectWithStreamWithServiceResponseAsync(image).map(new Func1>, List>() { @Override public List call(ServiceResponse> response) { return response.body(); @@ -960,22 +1240,91 @@ public List call(ServiceResponse> response) { * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. * * @param image An image stream. - * @param detectWithStreamOptionalParameter 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<DetectedFace> object */ - public Observable>> detectWithStreamWithServiceResponseAsync(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable>> detectWithStreamWithServiceResponseAsync(byte[] image) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (image == null) { throw new IllegalArgumentException("Parameter image is required and cannot be null."); } - final Boolean returnFaceId = detectWithStreamOptionalParameter != null ? detectWithStreamOptionalParameter.returnFaceId() : null; - final Boolean returnFaceLandmarks = detectWithStreamOptionalParameter != null ? detectWithStreamOptionalParameter.returnFaceLandmarks() : null; - final List returnFaceAttributes = detectWithStreamOptionalParameter != null ? detectWithStreamOptionalParameter.returnFaceAttributes() : null; + final Boolean returnFaceId = null; + final Boolean returnFaceLandmarks = null; + final List returnFaceAttributes = null; + final RecognitionModel recognitionModel = null; + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String returnFaceAttributesConverted = this.client.serializerAdapter().serializeList(returnFaceAttributes, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.detectWithStream(returnFaceId, returnFaceLandmarks, returnFaceAttributesConverted, imageConverted, recognitionModel, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = detectWithStreamDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<DetectedFace> object if successful. + */ + public List detectWithStream(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel) { + return detectWithStreamWithServiceResponseAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel).toBlocking().single().body(); + } + + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> detectWithStreamAsync(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(detectWithStreamWithServiceResponseAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel), serviceCallback); + } - return detectWithStreamWithServiceResponseAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes); + /** + * Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes. + * + * @param image An image stream. + * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. + * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. + * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<DetectedFace> object + */ + public Observable> detectWithStreamAsync(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel) { + return detectWithStreamWithServiceResponseAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); } /** @@ -985,21 +1334,22 @@ public Observable>> detectWithStreamWithServi * @param returnFaceId A value indicating whether the operation should return faceIds of detected faces. * @param returnFaceLandmarks A value indicating whether the operation should return landmarks of the detected faces. * @param returnFaceAttributes Analyze and return the one or more specified face attributes in the comma-separated string like "returnFaceAttributes=age,gender". Supported face attributes include age, gender, headPose, smile, facialHair, glasses and emotion. Note that each face attribute analysis has additional computational and time cost. + * @param recognitionModel Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. Possible values include: 'recognition_01', 'recognition_02' + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<DetectedFace> object */ - public Observable>> detectWithStreamWithServiceResponseAsync(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable>> detectWithStreamWithServiceResponseAsync(byte[] image, Boolean returnFaceId, Boolean returnFaceLandmarks, List returnFaceAttributes, RecognitionModel recognitionModel, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (image == null) { throw new IllegalArgumentException("Parameter image is required and cannot be null."); } Validator.validate(returnFaceAttributes); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - String returnFaceAttributesConverted = this.client.serializerAdapter().serializeList(returnFaceAttributes, CollectionFormat.CSV); - RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); - return service.detectWithStream(returnFaceId, returnFaceLandmarks, returnFaceAttributesConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String returnFaceAttributesConverted = this.client.serializerAdapter().serializeList(returnFaceAttributes, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.detectWithStream(returnFaceId, returnFaceLandmarks, returnFaceAttributesConverted, imageConverted, recognitionModel, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>>() { @Override public Observable>> call(Response response) { @@ -1020,67 +1370,4 @@ private ServiceResponse> detectWithStreamDelegate(Response returnFaceAttributes; - - /** - * Constructor. - * @param parent the parent object. - */ - FacesDetectWithStreamParameters(FacesImpl parent) { - this.parent = parent; - } - - @Override - public FacesDetectWithStreamParameters withImage(byte[] image) { - this.image = image; - return this; - } - - @Override - public FacesDetectWithStreamParameters withReturnFaceId(Boolean returnFaceId) { - this.returnFaceId = returnFaceId; - return this; - } - - @Override - public FacesDetectWithStreamParameters withReturnFaceLandmarks(Boolean returnFaceLandmarks) { - this.returnFaceLandmarks = returnFaceLandmarks; - return this; - } - - @Override - public FacesDetectWithStreamParameters withReturnFaceAttributes(List returnFaceAttributes) { - this.returnFaceAttributes = returnFaceAttributes; - return this; - } - - @Override - public List execute() { - return detectWithStreamWithServiceResponseAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes).toBlocking().single().body(); - } - - @Override - public Observable> executeAsync() { - return detectWithStreamWithServiceResponseAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes).map(new Func1>, List>() { - @Override - public List call(ServiceResponse> response) { - return response.body(); - } - }); - } - } - } diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargeFaceListsImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargeFaceListsImpl.java new file mode 100644 index 000000000000..bf9bd0a52bc4 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargeFaceListsImpl.java @@ -0,0 +1,2050 @@ +/** + * 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.implementation; + +import retrofit2.Retrofit; +import com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists; +import com.google.common.base.Joiner; +import com.google.common.reflect.TypeToken; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ImageUrl; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.LargeFaceList; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.MetaDataContract; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.NameAndUserDataContract; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TrainingStatus; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateFaceRequest; +import com.microsoft.rest.CollectionFormat; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import com.microsoft.rest.Validator; +import java.io.InputStream; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import okhttp3.MediaType; +import okhttp3.RequestBody; +import okhttp3.ResponseBody; +import retrofit2.http.Body; +import retrofit2.http.GET; +import retrofit2.http.Header; +import retrofit2.http.Headers; +import retrofit2.http.HTTP; +import retrofit2.http.PATCH; +import retrofit2.http.Path; +import retrofit2.http.POST; +import retrofit2.http.PUT; +import retrofit2.http.Query; +import retrofit2.Response; +import rx.functions.Func1; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in LargeFaceLists. + */ +public class LargeFaceListsImpl implements LargeFaceLists { + /** The Retrofit service to perform REST calls. */ + private LargeFaceListsService service; + /** The service client containing this operation class. */ + private FaceClientImpl client; + + /** + * Initializes an instance of LargeFaceListsImpl. + * + * @param retrofit the Retrofit instance built from a Retrofit Builder. + * @param client the instance of the service client containing this operation class. + */ + public LargeFaceListsImpl(Retrofit retrofit, FaceClientImpl client) { + this.service = retrofit.create(LargeFaceListsService.class); + this.client = client; + } + + /** + * The interface defining all the services for LargeFaceLists to be + * used by Retrofit to perform actually REST calls. + */ + interface LargeFaceListsService { + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists create" }) + @PUT("largefacelists/{largeFaceListId}") + Observable> create(@Path("largeFaceListId") String largeFaceListId, @Header("accept-language") String acceptLanguage, @Body MetaDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists get" }) + @GET("largefacelists/{largeFaceListId}") + Observable> get(@Path("largeFaceListId") String largeFaceListId, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists update" }) + @PATCH("largefacelists/{largeFaceListId}") + Observable> update(@Path("largeFaceListId") String largeFaceListId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists delete" }) + @HTTP(path = "largefacelists/{largeFaceListId}", method = "DELETE", hasBody = true) + Observable> delete(@Path("largeFaceListId") String largeFaceListId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists getTrainingStatus" }) + @GET("largefacelists/{largeFaceListId}/training") + Observable> getTrainingStatus(@Path("largeFaceListId") String largeFaceListId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists list" }) + @GET("largefacelists") + Observable> list(@Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists train" }) + @POST("largefacelists/{largeFaceListId}/train") + Observable> train(@Path("largeFaceListId") String largeFaceListId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists deleteFace" }) + @HTTP(path = "largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}", method = "DELETE", hasBody = true) + Observable> deleteFace(@Path("largeFaceListId") String largeFaceListId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists getFace" }) + @GET("largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}") + Observable> getFace(@Path("largeFaceListId") String largeFaceListId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists updateFace" }) + @PATCH("largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}") + Observable> updateFace(@Path("largeFaceListId") String largeFaceListId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Body UpdateFaceRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists addFaceFromUrl" }) + @POST("largefacelists/{largeFaceListId}/persistedfaces") + Observable> addFaceFromUrl(@Path("largeFaceListId") String largeFaceListId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Header("accept-language") String acceptLanguage, @Body ImageUrl imageUrl, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists listFaces" }) + @GET("largefacelists/{largeFaceListId}/persistedfaces") + Observable> listFaces(@Path("largeFaceListId") String largeFaceListId, @Query("start") String start, @Query("top") Integer top, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/octet-stream", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargeFaceLists addFaceFromStream" }) + @POST("largefacelists/{largeFaceListId}/persistedfaces") + Observable> addFaceFromStream(@Path("largeFaceListId") String largeFaceListId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Body RequestBody image, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 + */ + public void create(String largeFaceListId) { + createWithServiceResponseAsync(largeFaceListId).toBlocking().single().body(); + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String largeFaceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(largeFaceListId), serviceCallback); + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable createAsync(String largeFaceListId) { + return createWithServiceResponseAsync(largeFaceListId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> createWithServiceResponseAsync(String largeFaceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + final String name = null; + final String userData = null; + final RecognitionModel recognitionModel = null; + MetaDataContract body = new MetaDataContract(); + body.withName(null); + body.withUserData(null); + body.withRecognitionModel(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(largeFaceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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 + */ + public void create(String largeFaceListId, String name, String userData, RecognitionModel recognitionModel) { + createWithServiceResponseAsync(largeFaceListId, name, userData, recognitionModel).toBlocking().single().body(); + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String largeFaceListId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(largeFaceListId, name, userData, recognitionModel), serviceCallback); + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable createAsync(String largeFaceListId, String name, String userData, RecognitionModel recognitionModel) { + return createWithServiceResponseAsync(largeFaceListId, name, userData, recognitionModel).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Create an empty large face list with user-specified largeFaceListId, name, an optional userData and recognitionModel. + <br /> Large face list is a list of faces, up to 1,000,000 faces, and used by [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + <br /> After creation, user should use [LargeFaceList Face - Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the faces and [LargeFaceList - Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it ready for [Face - Find Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image will be stored. Only the extracted face features are stored on server until [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Find Similar is used for scenario like finding celebrity-like faces, similar face filtering, or as a light way face identification. But if the actual use is to identify person, please use [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) / [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) and [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br/>'recognitionModel' should be specified to associate with this large face list. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large face list will use the recognition model that's already associated with the collection. Existing face features in a large face list can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargeFaceList- Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those large face lists created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large face list quota: + * Free-tier subscription quota: 64 large face lists. + * S0-tier subscription quota: 1,000,000 large face lists. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> createWithServiceResponseAsync(String largeFaceListId, String name, String userData, RecognitionModel recognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + MetaDataContract body = new MetaDataContract(); + body.withName(name); + body.withUserData(userData); + body.withRecognitionModel(recognitionModel); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(largeFaceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse createDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 LargeFaceList object if successful. + */ + public LargeFaceList get(String largeFaceListId) { + return getWithServiceResponseAsync(largeFaceListId).toBlocking().single().body(); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getAsync(String largeFaceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(largeFaceListId), serviceCallback); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + public Observable getAsync(String largeFaceListId) { + return getWithServiceResponseAsync(largeFaceListId).map(new Func1, LargeFaceList>() { + @Override + public LargeFaceList call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + public Observable> getWithServiceResponseAsync(String largeFaceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(largeFaceListId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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 LargeFaceList object if successful. + */ + public LargeFaceList get(String largeFaceListId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(largeFaceListId, returnRecognitionModel).toBlocking().single().body(); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getAsync(String largeFaceListId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(largeFaceListId, returnRecognitionModel), serviceCallback); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + public Observable getAsync(String largeFaceListId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(largeFaceListId, returnRecognitionModel).map(new Func1, LargeFaceList>() { + @Override + public LargeFaceList call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve a large face list’s largeFaceListId, name, userData and recognitionModel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargeFaceList object + */ + public Observable> getWithServiceResponseAsync(String largeFaceListId, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(largeFaceListId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 + */ + public void update(String largeFaceListId) { + updateWithServiceResponseAsync(largeFaceListId).toBlocking().single().body(); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String largeFaceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(largeFaceListId), serviceCallback); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String largeFaceListId) { + return updateWithServiceResponseAsync(largeFaceListId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(String largeFaceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(largeFaceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 + */ + public void update(String largeFaceListId, String name, String userData) { + updateWithServiceResponseAsync(largeFaceListId, name, userData).toBlocking().single().body(); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String largeFaceListId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(largeFaceListId, name, userData), serviceCallback); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String largeFaceListId, String name, String userData) { + return updateWithServiceResponseAsync(largeFaceListId, name, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update information of a large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(String largeFaceListId, String name, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(largeFaceListId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse updateDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 + */ + public void delete(String largeFaceListId) { + deleteWithServiceResponseAsync(largeFaceListId).toBlocking().single().body(); + } + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteAsync(String largeFaceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteWithServiceResponseAsync(largeFaceListId), serviceCallback); + } + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteAsync(String largeFaceListId) { + return deleteWithServiceResponseAsync(largeFaceListId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete a specified large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteWithServiceResponseAsync(String largeFaceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.delete(largeFaceListId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @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. + */ + public TrainingStatus getTrainingStatus(String largeFaceListId) { + return getTrainingStatusWithServiceResponseAsync(largeFaceListId).toBlocking().single().body(); + } + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getTrainingStatusAsync(String largeFaceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getTrainingStatusWithServiceResponseAsync(largeFaceListId), serviceCallback); + } + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + public Observable getTrainingStatusAsync(String largeFaceListId) { + return getTrainingStatusWithServiceResponseAsync(largeFaceListId).map(new Func1, TrainingStatus>() { + @Override + public TrainingStatus call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve the training status of a large face list (completed or ongoing). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + public Observable> getTrainingStatusWithServiceResponseAsync(String largeFaceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.getTrainingStatus(largeFaceListId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getTrainingStatusDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getTrainingStatusDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @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<LargeFaceList> object if successful. + */ + public List list() { + return listWithServiceResponseAsync().toBlocking().single().body(); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(), serviceCallback); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + public Observable> listAsync() { + return listWithServiceResponseAsync().map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + public Observable>> listWithServiceResponseAsync() { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<LargeFaceList> object if successful. + */ + public List list(Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(returnRecognitionModel).toBlocking().single().body(); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(Boolean returnRecognitionModel, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(returnRecognitionModel), serviceCallback); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + public Observable> listAsync(Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(returnRecognitionModel).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List large face lists’ information of largeFaceListId, name, userData and recognitionModel. <br /> + To get face information inside largeFaceList use [LargeFaceList Face - Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br /> + * Large face lists are stored in alphabetical order of largeFaceListId. + * "start" parameter (string, optional) is a user-provided largeFaceListId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person lists: "list1", ..., "list5". + <br /> "start=&top=" will return all 5 lists. + <br /> "start=&top=2" will return "list1", "list2". + <br /> "start=list2&top=3" will return "list3", "list4", "list5". + * + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargeFaceList> object + */ + public Observable>> listWithServiceResponseAsync(Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse> listDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory()., APIErrorException>newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken>() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @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 + */ + public void train(String largeFaceListId) { + trainWithServiceResponseAsync(largeFaceListId).toBlocking().single().body(); + } + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture trainAsync(String largeFaceListId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(trainWithServiceResponseAsync(largeFaceListId), serviceCallback); + } + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable trainAsync(String largeFaceListId) { + return trainWithServiceResponseAsync(largeFaceListId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Queue a large face list training task, the training task may not be started immediately. + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> trainWithServiceResponseAsync(String largeFaceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.train(largeFaceListId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = trainDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse trainDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(202, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 + */ + public void deleteFace(String largeFaceListId, UUID persistedFaceId) { + deleteFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId).toBlocking().single().body(); + } + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteFaceAsync(String largeFaceListId, UUID persistedFaceId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId), serviceCallback); + } + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteFaceAsync(String largeFaceListId, UUID persistedFaceId) { + return deleteFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete a face from a large face list by specified largeFaceListId and persistedFaceId. + <br /> Adding/deleting faces to/from a same large face list are processed sequentially and to/from different large face lists are in parallel. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.deleteFace(largeFaceListId, persistedFaceId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteFaceDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 PersistedFace object if successful. + */ + public PersistedFace getFace(String largeFaceListId, UUID persistedFaceId) { + return getFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId).toBlocking().single().body(); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getFaceAsync(String largeFaceListId, UUID persistedFaceId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId), serviceCallback); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable getFaceAsync(String largeFaceListId, UUID persistedFaceId) { + return getFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId and its belonging largeFaceListId). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> getFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.getFace(largeFaceListId, persistedFaceId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getFaceDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 + */ + public void updateFace(String largeFaceListId, UUID persistedFaceId) { + updateFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId).toBlocking().single().body(); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateFaceAsync(String largeFaceListId, UUID persistedFaceId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId), serviceCallback); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateFaceAsync(String largeFaceListId, UUID persistedFaceId) { + return updateFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + final String userData = null; + UpdateFaceRequest body = new UpdateFaceRequest(); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.updateFace(largeFaceListId, persistedFaceId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @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 + */ + public void updateFace(String largeFaceListId, UUID persistedFaceId, String userData) { + updateFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId, userData).toBlocking().single().body(); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateFaceAsync(String largeFaceListId, UUID persistedFaceId, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId, userData), serviceCallback); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateFaceAsync(String largeFaceListId, UUID persistedFaceId, String userData) { + return updateFaceWithServiceResponseAsync(largeFaceListId, persistedFaceId, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update a persisted face's userData field. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateFaceWithServiceResponseAsync(String largeFaceListId, UUID persistedFaceId, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + UpdateFaceRequest body = new UpdateFaceRequest(); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.updateFace(largeFaceListId, persistedFaceId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse updateFaceDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromUrl(String largeFaceListId, String url) { + return addFaceFromUrlWithServiceResponseAsync(largeFaceListId, url).toBlocking().single().body(); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromUrlAsync(String largeFaceListId, String url, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(largeFaceListId, url), serviceCallback); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromUrlAsync(String largeFaceListId, String url) { + return addFaceFromUrlWithServiceResponseAsync(largeFaceListId, url).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromUrlWithServiceResponseAsync(String largeFaceListId, String url) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (url == null) { + throw new IllegalArgumentException("Parameter url is required and cannot be null."); + } + final String userData = null; + final List targetFace = null; + ImageUrl imageUrl = new ImageUrl(); + imageUrl.withUrl(url); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); + return service.addFaceFromUrl(largeFaceListId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromUrlDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromUrl(String largeFaceListId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(largeFaceListId, url, userData, targetFace).toBlocking().single().body(); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromUrlAsync(String largeFaceListId, String url, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(largeFaceListId, url, userData, targetFace), serviceCallback); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromUrlAsync(String largeFaceListId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(largeFaceListId, url, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a specified large face list, up to 1,000,000 faces. + <br /> To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargeFaceList Face - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4) or [LargeFaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same face list are processed sequentially and to/from different face lists are in parallel. + Quota: + * Free-tier subscription quota: 1,000 faces per large face list. + * S0-tier subscription quota: 1,000,000 faces per large face list. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromUrlWithServiceResponseAsync(String largeFaceListId, String url, String userData, List targetFace) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (url == null) { + throw new IllegalArgumentException("Parameter url is required and cannot be null."); + } + Validator.validate(targetFace); + ImageUrl imageUrl = new ImageUrl(); + imageUrl.withUrl(url); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); + return service.addFaceFromUrl(largeFaceListId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromUrlDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse addFaceFromUrlDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @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<PersistedFace> object if successful. + */ + public List listFaces(String largeFaceListId) { + return listFacesWithServiceResponseAsync(largeFaceListId).toBlocking().single().body(); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listFacesAsync(String largeFaceListId, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listFacesWithServiceResponseAsync(largeFaceListId), serviceCallback); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + public Observable> listFacesAsync(String largeFaceListId) { + return listFacesWithServiceResponseAsync(largeFaceListId).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + public Observable>> listFacesWithServiceResponseAsync(String largeFaceListId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + final String start = null; + final Integer top = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.listFaces(largeFaceListId, start, top, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listFacesDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @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<PersistedFace> object if successful. + */ + public List listFaces(String largeFaceListId, String start, Integer top) { + return listFacesWithServiceResponseAsync(largeFaceListId, start, top).toBlocking().single().body(); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listFacesAsync(String largeFaceListId, String start, Integer top, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listFacesWithServiceResponseAsync(largeFaceListId, start, top), serviceCallback); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + public Observable> listFacesAsync(String largeFaceListId, String start, Integer top) { + return listFacesWithServiceResponseAsync(largeFaceListId, start, top).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all faces in a large face list, and retrieve face information (including userData and persistedFaceIds of registered faces of the face). + * + * @param largeFaceListId Id referencing a particular large face list. + * @param start Starting face id to return (used to list a range of faces). + * @param top Number of faces to return starting with the face id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersistedFace> object + */ + public Observable>> listFacesWithServiceResponseAsync(String largeFaceListId, String start, Integer top) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.listFaces(largeFaceListId, start, top, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listFacesDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse> listFacesDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory()., APIErrorException>newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken>() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromStream(String largeFaceListId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(largeFaceListId, image).toBlocking().single().body(); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromStreamAsync(String largeFaceListId, byte[] image, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(largeFaceListId, image), serviceCallback); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromStreamAsync(String largeFaceListId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(largeFaceListId, image).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromStreamWithServiceResponseAsync(String largeFaceListId, byte[] image) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (image == null) { + throw new IllegalArgumentException("Parameter image is required and cannot be null."); + } + final String userData = null; + final List targetFace = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.addFaceFromStream(largeFaceListId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromStreamDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromStream(String largeFaceListId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(largeFaceListId, image, userData, targetFace).toBlocking().single().body(); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromStreamAsync(String largeFaceListId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(largeFaceListId, image, userData, targetFace), serviceCallback); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromStreamAsync(String largeFaceListId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(largeFaceListId, image, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a large face list. The input face is specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face, and persistedFaceId will not expire. + * + * @param largeFaceListId Id referencing a particular large face list. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromStreamWithServiceResponseAsync(String largeFaceListId, byte[] image, String userData, List targetFace) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largeFaceListId == null) { + throw new IllegalArgumentException("Parameter largeFaceListId is required and cannot be null."); + } + if (image == null) { + throw new IllegalArgumentException("Parameter image is required and cannot be null."); + } + Validator.validate(targetFace); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.addFaceFromStream(largeFaceListId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromStreamDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse addFaceFromStreamDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupPersonsImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupPersonsImpl.java new file mode 100644 index 000000000000..50ad0b87c3c1 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupPersonsImpl.java @@ -0,0 +1,1579 @@ +/** + * 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.implementation; + +import retrofit2.Retrofit; +import com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons; +import com.google.common.base.Joiner; +import com.google.common.reflect.TypeToken; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ImageUrl; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.NameAndUserDataContract; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.Person; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateFaceRequest; +import com.microsoft.rest.CollectionFormat; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import com.microsoft.rest.Validator; +import java.io.InputStream; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import okhttp3.MediaType; +import okhttp3.RequestBody; +import okhttp3.ResponseBody; +import retrofit2.http.Body; +import retrofit2.http.GET; +import retrofit2.http.Header; +import retrofit2.http.Headers; +import retrofit2.http.HTTP; +import retrofit2.http.PATCH; +import retrofit2.http.Path; +import retrofit2.http.POST; +import retrofit2.http.Query; +import retrofit2.Response; +import rx.functions.Func1; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in LargePersonGroupPersons. + */ +public class LargePersonGroupPersonsImpl implements LargePersonGroupPersons { + /** The Retrofit service to perform REST calls. */ + private LargePersonGroupPersonsService service; + /** The service client containing this operation class. */ + private FaceClientImpl client; + + /** + * Initializes an instance of LargePersonGroupPersonsImpl. + * + * @param retrofit the Retrofit instance built from a Retrofit Builder. + * @param client the instance of the service client containing this operation class. + */ + public LargePersonGroupPersonsImpl(Retrofit retrofit, FaceClientImpl client) { + this.service = retrofit.create(LargePersonGroupPersonsService.class); + this.client = client; + } + + /** + * The interface defining all the services for LargePersonGroupPersons to be + * used by Retrofit to perform actually REST calls. + */ + interface LargePersonGroupPersonsService { + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons create" }) + @POST("largepersongroups/{largePersonGroupId}/persons") + Observable> create(@Path("largePersonGroupId") String largePersonGroupId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons list" }) + @GET("largepersongroups/{largePersonGroupId}/persons") + Observable> list(@Path("largePersonGroupId") String largePersonGroupId, @Query("start") String start, @Query("top") Integer top, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons delete" }) + @HTTP(path = "largepersongroups/{largePersonGroupId}/persons/{personId}", method = "DELETE", hasBody = true) + Observable> delete(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons get" }) + @GET("largepersongroups/{largePersonGroupId}/persons/{personId}") + Observable> get(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons update" }) + @PATCH("largepersongroups/{largePersonGroupId}/persons/{personId}") + Observable> update(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons deleteFace" }) + @HTTP(path = "largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}", method = "DELETE", hasBody = true) + Observable> deleteFace(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons getFace" }) + @GET("largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}") + Observable> getFace(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons updateFace" }) + @PATCH("largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}") + Observable> updateFace(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Body UpdateFaceRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons addFaceFromUrl" }) + @POST("largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces") + Observable> addFaceFromUrl(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Header("accept-language") String acceptLanguage, @Body ImageUrl imageUrl, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/octet-stream", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroupPersons addFaceFromStream" }) + @POST("largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces") + Observable> addFaceFromStream(@Path("largePersonGroupId") String largePersonGroupId, @Path("personId") UUID personId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Body RequestBody image, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large 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 Person object if successful. + */ + public Person create(String largePersonGroupId) { + return createWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + public Observable createAsync(String largePersonGroupId) { + return createWithServiceResponseAsync(largePersonGroupId).map(new Func1, Person>() { + @Override + public Person call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + public Observable> createWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(largePersonGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 Person object if successful. + */ + public Person create(String largePersonGroupId, String name, String userData) { + return createWithServiceResponseAsync(largePersonGroupId, name, userData).toBlocking().single().body(); + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String largePersonGroupId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(largePersonGroupId, name, userData), serviceCallback); + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + public Observable createAsync(String largePersonGroupId, String name, String userData) { + return createWithServiceResponseAsync(largePersonGroupId, name, userData).map(new Func1, Person>() { + @Override + public Person call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Create a new person in a specified large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + public Observable> createWithServiceResponseAsync(String largePersonGroupId, String name, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(largePersonGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse createDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large 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 List<Person> object if successful. + */ + public List list(String largePersonGroupId) { + return listWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(String largePersonGroupId, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + public Observable> listAsync(String largePersonGroupId) { + return listWithServiceResponseAsync(largePersonGroupId).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + public Observable>> listWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + final String start = null; + final Integer top = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(largePersonGroupId, start, top, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @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<Person> object if successful. + */ + public List list(String largePersonGroupId, String start, Integer top) { + return listWithServiceResponseAsync(largePersonGroupId, start, top).toBlocking().single().body(); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(String largePersonGroupId, String start, Integer top, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(largePersonGroupId, start, top), serviceCallback); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + public Observable> listAsync(String largePersonGroupId, String start, Integer top) { + return listWithServiceResponseAsync(largePersonGroupId, start, top).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all persons in a large person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + public Observable>> listWithServiceResponseAsync(String largePersonGroupId, String start, Integer top) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(largePersonGroupId, start, top, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse> listDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory()., APIErrorException>newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken>() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @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 + */ + public void delete(String largePersonGroupId, UUID personId) { + deleteWithServiceResponseAsync(largePersonGroupId, personId).toBlocking().single().body(); + } + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteAsync(String largePersonGroupId, UUID personId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteWithServiceResponseAsync(largePersonGroupId, personId), serviceCallback); + } + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteAsync(String largePersonGroupId, UUID personId) { + return deleteWithServiceResponseAsync(largePersonGroupId, personId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete an existing person from a large person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteWithServiceResponseAsync(String largePersonGroupId, UUID personId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.delete(largePersonGroupId, personId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @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 Person object if successful. + */ + public Person get(String largePersonGroupId, UUID personId) { + return getWithServiceResponseAsync(largePersonGroupId, personId).toBlocking().single().body(); + } + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getAsync(String largePersonGroupId, UUID personId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(largePersonGroupId, personId), serviceCallback); + } + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + public Observable getAsync(String largePersonGroupId, UUID personId) { + return getWithServiceResponseAsync(largePersonGroupId, personId).map(new Func1, Person>() { + @Override + public Person call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve a person's name and userData, and the persisted faceIds representing the registered person face feature. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + public Observable> getWithServiceResponseAsync(String largePersonGroupId, UUID personId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(largePersonGroupId, personId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @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 + */ + public void update(String largePersonGroupId, UUID personId) { + updateWithServiceResponseAsync(largePersonGroupId, personId).toBlocking().single().body(); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String largePersonGroupId, UUID personId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(largePersonGroupId, personId), serviceCallback); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String largePersonGroupId, UUID personId) { + return updateWithServiceResponseAsync(largePersonGroupId, personId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(String largePersonGroupId, UUID personId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(largePersonGroupId, personId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 + */ + public void update(String largePersonGroupId, UUID personId, String name, String userData) { + updateWithServiceResponseAsync(largePersonGroupId, personId, name, userData).toBlocking().single().body(); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String largePersonGroupId, UUID personId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(largePersonGroupId, personId, name, userData), serviceCallback); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String largePersonGroupId, UUID personId, String name, String userData) { + return updateWithServiceResponseAsync(largePersonGroupId, personId, name, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update name or userData of a person. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(String largePersonGroupId, UUID personId, String name, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(largePersonGroupId, personId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse updateDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 + */ + public void deleteFace(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + deleteFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId).toBlocking().single().body(); + } + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId), serviceCallback); + } + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + return deleteFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete a face from a person in a large person group by specified largePersonGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.deleteFace(largePersonGroupId, personId, persistedFaceId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteFaceDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 PersistedFace object if successful. + */ + public PersistedFace getFace(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + return getFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId).toBlocking().single().body(); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId), serviceCallback); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable getFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + return getFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve information about a persisted face (specified by persistedFaceId, personId and its belonging largePersonGroupId). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> getFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.getFace(largePersonGroupId, personId, persistedFaceId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getFaceDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @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 + */ + public void updateFace(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + updateFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId).toBlocking().single().body(); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId), serviceCallback); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + return updateFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + final String userData = null; + UpdateFaceRequest body = new UpdateFaceRequest(); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.updateFace(largePersonGroupId, personId, persistedFaceId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @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 + */ + public void updateFace(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData) { + updateFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId, userData).toBlocking().single().body(); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId, userData), serviceCallback); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateFaceAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData) { + return updateFaceWithServiceResponseAsync(largePersonGroupId, personId, persistedFaceId, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update a person persisted face's userData field. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateFaceWithServiceResponseAsync(String largePersonGroupId, UUID personId, UUID persistedFaceId, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (persistedFaceId == null) { + throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); + } + UpdateFaceRequest body = new UpdateFaceRequest(); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.updateFace(largePersonGroupId, personId, persistedFaceId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse updateFaceDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromUrl(String largePersonGroupId, UUID personId, String url) { + return addFaceFromUrlWithServiceResponseAsync(largePersonGroupId, personId, url).toBlocking().single().body(); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(largePersonGroupId, personId, url), serviceCallback); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url) { + return addFaceFromUrlWithServiceResponseAsync(largePersonGroupId, personId, url).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromUrlWithServiceResponseAsync(String largePersonGroupId, UUID personId, String url) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (url == null) { + throw new IllegalArgumentException("Parameter url is required and cannot be null."); + } + final String userData = null; + final List targetFace = null; + ImageUrl imageUrl = new ImageUrl(); + imageUrl.withUrl(url); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); + return service.addFaceFromUrl(largePersonGroupId, personId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromUrlDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromUrl(String largePersonGroupId, UUID personId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(largePersonGroupId, personId, url, userData, targetFace).toBlocking().single().body(); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(largePersonGroupId, personId, url, userData, targetFace), serviceCallback); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromUrlAsync(String largePersonGroupId, UUID personId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(largePersonGroupId, personId, url, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromUrlWithServiceResponseAsync(String largePersonGroupId, UUID personId, String url, String userData, List targetFace) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (url == null) { + throw new IllegalArgumentException("Parameter url is required and cannot be null."); + } + Validator.validate(targetFace); + ImageUrl imageUrl = new ImageUrl(); + imageUrl.withUrl(url); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); + return service.addFaceFromUrl(largePersonGroupId, personId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromUrlDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse addFaceFromUrlDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromStream(String largePersonGroupId, UUID personId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(largePersonGroupId, personId, image).toBlocking().single().body(); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(largePersonGroupId, personId, image), serviceCallback); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(largePersonGroupId, personId, image).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromStreamWithServiceResponseAsync(String largePersonGroupId, UUID personId, byte[] image) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (image == null) { + throw new IllegalArgumentException("Parameter image is required and cannot be null."); + } + final String userData = null; + final List targetFace = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.addFaceFromStream(largePersonGroupId, personId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromStreamDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromStream(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(largePersonGroupId, personId, image, userData, targetFace).toBlocking().single().body(); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(largePersonGroupId, personId, image, userData, targetFace), serviceCallback); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromStreamAsync(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(largePersonGroupId, personId, image, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromStreamWithServiceResponseAsync(String largePersonGroupId, UUID personId, byte[] image, String userData, List targetFace) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + if (personId == null) { + throw new IllegalArgumentException("Parameter personId is required and cannot be null."); + } + if (image == null) { + throw new IllegalArgumentException("Parameter image is required and cannot be null."); + } + Validator.validate(targetFace); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.addFaceFromStream(largePersonGroupId, personId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromStreamDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse addFaceFromStreamDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupsImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupsImpl.java new file mode 100644 index 000000000000..eb83ed1bd89e --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/LargePersonGroupsImpl.java @@ -0,0 +1,1099 @@ +/** + * 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.implementation; + +import retrofit2.Retrofit; +import com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups; +import com.google.common.base.Joiner; +import com.google.common.reflect.TypeToken; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.LargePersonGroup; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.MetaDataContract; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.NameAndUserDataContract; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TrainingStatus; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; +import java.util.List; +import okhttp3.ResponseBody; +import retrofit2.http.Body; +import retrofit2.http.GET; +import retrofit2.http.Header; +import retrofit2.http.Headers; +import retrofit2.http.HTTP; +import retrofit2.http.PATCH; +import retrofit2.http.Path; +import retrofit2.http.POST; +import retrofit2.http.PUT; +import retrofit2.http.Query; +import retrofit2.Response; +import rx.functions.Func1; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in LargePersonGroups. + */ +public class LargePersonGroupsImpl implements LargePersonGroups { + /** The Retrofit service to perform REST calls. */ + private LargePersonGroupsService service; + /** The service client containing this operation class. */ + private FaceClientImpl client; + + /** + * Initializes an instance of LargePersonGroupsImpl. + * + * @param retrofit the Retrofit instance built from a Retrofit Builder. + * @param client the instance of the service client containing this operation class. + */ + public LargePersonGroupsImpl(Retrofit retrofit, FaceClientImpl client) { + this.service = retrofit.create(LargePersonGroupsService.class); + this.client = client; + } + + /** + * The interface defining all the services for LargePersonGroups to be + * used by Retrofit to perform actually REST calls. + */ + interface LargePersonGroupsService { + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups create" }) + @PUT("largepersongroups/{largePersonGroupId}") + Observable> create(@Path("largePersonGroupId") String largePersonGroupId, @Header("accept-language") String acceptLanguage, @Body MetaDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups delete" }) + @HTTP(path = "largepersongroups/{largePersonGroupId}", method = "DELETE", hasBody = true) + Observable> delete(@Path("largePersonGroupId") String largePersonGroupId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups get" }) + @GET("largepersongroups/{largePersonGroupId}") + Observable> get(@Path("largePersonGroupId") String largePersonGroupId, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups update" }) + @PATCH("largepersongroups/{largePersonGroupId}") + Observable> update(@Path("largePersonGroupId") String largePersonGroupId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups getTrainingStatus" }) + @GET("largepersongroups/{largePersonGroupId}/training") + Observable> getTrainingStatus(@Path("largePersonGroupId") String largePersonGroupId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups list" }) + @GET("largepersongroups") + Observable> list(@Query("start") String start, @Query("top") Integer top, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.LargePersonGroups train" }) + @POST("largepersongroups/{largePersonGroupId}/train") + Observable> train(@Path("largePersonGroupId") String largePersonGroupId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large 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 + */ + public void create(String largePersonGroupId) { + createWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable createAsync(String largePersonGroupId) { + return createWithServiceResponseAsync(largePersonGroupId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> createWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + final String name = null; + final String userData = null; + final RecognitionModel recognitionModel = null; + MetaDataContract body = new MetaDataContract(); + body.withName(null); + body.withUserData(null); + body.withRecognitionModel(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(largePersonGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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 + */ + public void create(String largePersonGroupId, String name, String userData, RecognitionModel recognitionModel) { + createWithServiceResponseAsync(largePersonGroupId, name, userData, recognitionModel).toBlocking().single().body(); + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String largePersonGroupId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(largePersonGroupId, name, userData, recognitionModel), serviceCallback); + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable createAsync(String largePersonGroupId, String name, String userData, RecognitionModel recognitionModel) { + return createWithServiceResponseAsync(largePersonGroupId, name, userData, recognitionModel).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Create a new large person group with user-specified largePersonGroupId, name, an optional userData and recognitionModel. + <br /> A large person group is the container of the uploaded person data, including face recognition feature, and up to 1,000,000 + people. + <br /> After creation, use [LargePersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add person into the group, and call [LargePersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br/>'recognitionModel' should be specified to associate with this large person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing large person group will use the recognition model that's already associated with the collection. Existing face features in a large person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [LargePersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those large person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Large person group quota: + * Free-tier subscription quota: 1,000 large person groups. + * S0-tier subscription quota: 1,000,000 large person groups. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> createWithServiceResponseAsync(String largePersonGroupId, String name, String userData, RecognitionModel recognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + MetaDataContract body = new MetaDataContract(); + body.withName(name); + body.withUserData(userData); + body.withRecognitionModel(recognitionModel); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(largePersonGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse createDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large 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 + */ + public void delete(String largePersonGroupId) { + deleteWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteAsync(String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteAsync(String largePersonGroupId) { + return deleteWithServiceResponseAsync(largePersonGroupId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete an existing large person group. Persisted face features of all people in the large person group will also be deleted. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.delete(largePersonGroupId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large 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 LargePersonGroup object if successful. + */ + public LargePersonGroup get(String largePersonGroupId) { + return getWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getAsync(String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + public Observable getAsync(String largePersonGroupId) { + return getWithServiceResponseAsync(largePersonGroupId).map(new Func1, LargePersonGroup>() { + @Override + public LargePersonGroup call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + public Observable> getWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(largePersonGroupId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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 LargePersonGroup object if successful. + */ + public LargePersonGroup get(String largePersonGroupId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(largePersonGroupId, returnRecognitionModel).toBlocking().single().body(); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getAsync(String largePersonGroupId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(largePersonGroupId, returnRecognitionModel), serviceCallback); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + public Observable getAsync(String largePersonGroupId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(largePersonGroupId, returnRecognitionModel).map(new Func1, LargePersonGroup>() { + @Override + public LargePersonGroup call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve the information of a large person group, including its name, userData and recognitionModel. This API returns large person group information only, use [LargePersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) instead to retrieve person information under the large person group. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the LargePersonGroup object + */ + public Observable> getWithServiceResponseAsync(String largePersonGroupId, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(largePersonGroupId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large 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 + */ + public void update(String largePersonGroupId) { + updateWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String largePersonGroupId) { + return updateWithServiceResponseAsync(largePersonGroupId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(largePersonGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 + */ + public void update(String largePersonGroupId, String name, String userData) { + updateWithServiceResponseAsync(largePersonGroupId, name, userData).toBlocking().single().body(); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String largePersonGroupId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(largePersonGroupId, name, userData), serviceCallback); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String largePersonGroupId, String name, String userData) { + return updateWithServiceResponseAsync(largePersonGroupId, name, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update an existing large person group's display name and userData. The properties which does not appear in request body will not be updated. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(String largePersonGroupId, String name, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(largePersonGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse updateDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large 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. + */ + public TrainingStatus getTrainingStatus(String largePersonGroupId) { + return getTrainingStatusWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getTrainingStatusAsync(String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getTrainingStatusWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + public Observable getTrainingStatusAsync(String largePersonGroupId) { + return getTrainingStatusWithServiceResponseAsync(largePersonGroupId).map(new Func1, TrainingStatus>() { + @Override + public TrainingStatus call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve the training status of a large person group (completed or ongoing). + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainingStatus object + */ + public Observable> getTrainingStatusWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.getTrainingStatus(largePersonGroupId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getTrainingStatusDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getTrainingStatusDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @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<LargePersonGroup> object if successful. + */ + public List list() { + return listWithServiceResponseAsync().toBlocking().single().body(); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(), serviceCallback); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + public Observable> listAsync() { + return listWithServiceResponseAsync().map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + public Observable>> listWithServiceResponseAsync() { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + final String start = null; + final Integer top = null; + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(start, top, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<LargePersonGroup> object if successful. + */ + public List list(String start, Integer top, Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(start, top, returnRecognitionModel).toBlocking().single().body(); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(String start, Integer top, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(start, top, returnRecognitionModel), serviceCallback); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + public Observable> listAsync(String start, Integer top, Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(start, top, returnRecognitionModel).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all existing large person groups’ largePersonGroupId, name, userData and recognitionModel.<br /> + * Large person groups are stored in alphabetical order of largePersonGroupId. + * "start" parameter (string, optional) is a user-provided largePersonGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 large person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List large person groups from the least largePersonGroupId greater than the "start". + * @param top The number of large person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<LargePersonGroup> object + */ + public Observable>> listWithServiceResponseAsync(String start, Integer top, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(start, top, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse> listDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory()., APIErrorException>newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken>() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large 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 + */ + public void train(String largePersonGroupId) { + trainWithServiceResponseAsync(largePersonGroupId).toBlocking().single().body(); + } + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture trainAsync(String largePersonGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(trainWithServiceResponseAsync(largePersonGroupId), serviceCallback); + } + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable trainAsync(String largePersonGroupId) { + return trainWithServiceResponseAsync(largePersonGroupId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Queue a large person group training task, the training task may not be started immediately. + * + * @param largePersonGroupId Id referencing a particular large person group. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> trainWithServiceResponseAsync(String largePersonGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (largePersonGroupId == null) { + throw new IllegalArgumentException("Parameter largePersonGroupId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.train(largePersonGroupId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = trainDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse trainDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(202, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupPersonsImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupPersonsImpl.java index cf06d839bd97..962030eca21f 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupPersonsImpl.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupPersonsImpl.java @@ -8,12 +8,6 @@ package com.microsoft.azure.cognitiveservices.vision.faceapi.implementation; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.CreatePersonGroupPersonsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ListPersonGroupPersonsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdatePersonGroupPersonsOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateFaceOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddPersonFaceFromUrlOptionalParameter; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.AddPersonFaceFromStreamOptionalParameter; import retrofit2.Retrofit; import com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons; import com.google.common.base.Joiner; @@ -23,12 +17,13 @@ import com.microsoft.azure.cognitiveservices.vision.faceapi.models.NameAndUserDataContract; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersistedFace; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.Person; -import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdatePersonFaceRequest; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateFaceRequest; import com.microsoft.rest.CollectionFormat; import com.microsoft.rest.ServiceCallback; import com.microsoft.rest.ServiceFuture; import com.microsoft.rest.ServiceResponse; import com.microsoft.rest.Validator; +import java.io.InputStream; import java.io.IOException; import java.util.List; import java.util.UUID; @@ -56,7 +51,7 @@ public class PersonGroupPersonsImpl implements PersonGroupPersons { /** The Retrofit service to perform REST calls. */ private PersonGroupPersonsService service; /** The service client containing this operation class. */ - private FaceAPIImpl client; + private FaceClientImpl client; /** * Initializes an instance of PersonGroupPersonsImpl. @@ -64,7 +59,7 @@ public class PersonGroupPersonsImpl implements PersonGroupPersons { * @param retrofit the Retrofit instance built from a Retrofit Builder. * @param client the instance of the service client containing this operation class. */ - public PersonGroupPersonsImpl(Retrofit retrofit, FaceAPIImpl client) { + public PersonGroupPersonsImpl(Retrofit retrofit, FaceClientImpl client) { this.service = retrofit.create(PersonGroupPersonsService.class); this.client = client; } @@ -76,7 +71,7 @@ public PersonGroupPersonsImpl(Retrofit retrofit, FaceAPIImpl client) { interface PersonGroupPersonsService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons create" }) @POST("persongroups/{personGroupId}/persons") - Observable> create(@Path("personGroupId") String personGroupId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> create(@Path("personGroupId") String personGroupId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons list" }) @GET("persongroups/{personGroupId}/persons") @@ -92,68 +87,64 @@ interface PersonGroupPersonsService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons update" }) @PATCH("persongroups/{personGroupId}/persons/{personId}") - Observable> update(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> update(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons deleteFace" }) - @HTTP(path = "persongroups/{personGroupId}/persons/{personId}/persistedFaces/{persistedFaceId}", method = "DELETE", hasBody = true) + @HTTP(path = "persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}", method = "DELETE", hasBody = true) Observable> deleteFace(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons getFace" }) - @GET("persongroups/{personGroupId}/persons/{personId}/persistedFaces/{persistedFaceId}") + @GET("persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}") Observable> getFace(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons updateFace" }) - @PATCH("persongroups/{personGroupId}/persons/{personId}/persistedFaces/{persistedFaceId}") - Observable> updateFace(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Body UpdatePersonFaceRequest bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + @PATCH("persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}") + Observable> updateFace(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Path("persistedFaceId") UUID persistedFaceId, @Header("accept-language") String acceptLanguage, @Body UpdateFaceRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); - @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons addPersonFaceFromUrl" }) - @POST("persongroups/{personGroupId}/persons/{personId}/persistedFaces") - Observable> addPersonFaceFromUrl(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Header("accept-language") String acceptLanguage, @Body ImageUrl imageUrl, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons addFaceFromUrl" }) + @POST("persongroups/{personGroupId}/persons/{personId}/persistedfaces") + Observable> addFaceFromUrl(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Header("accept-language") String acceptLanguage, @Body ImageUrl imageUrl, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); - @Headers({ "Content-Type: application/octet-stream", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons addPersonFaceFromStream" }) - @POST("persongroups/{personGroupId}/persons/{personId}/persistedFaces") - Observable> addPersonFaceFromStream(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Body RequestBody image, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + @Headers({ "Content-Type: application/octet-stream", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroupPersons addFaceFromStream" }) + @POST("persongroups/{personGroupId}/persons/{personId}/persistedfaces") + Observable> addFaceFromStream(@Path("personGroupId") String personGroupId, @Path("personId") UUID personId, @Query("userData") String userData, @Query("targetFace") String targetFace, @Body RequestBody image, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); } - /** * Create a new person in a specified person group. * * @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 * @return the Person object if successful. */ - public Person create(String personGroupId, CreatePersonGroupPersonsOptionalParameter createOptionalParameter) { - return createWithServiceResponseAsync(personGroupId, createOptionalParameter).toBlocking().single().body(); + public Person create(String personGroupId) { + return createWithServiceResponseAsync(personGroupId).toBlocking().single().body(); } /** * Create a new person in a specified person group. * * @param personGroupId Id referencing a particular person group. - * @param createOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture createAsync(String personGroupId, CreatePersonGroupPersonsOptionalParameter createOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(createWithServiceResponseAsync(personGroupId, createOptionalParameter), serviceCallback); + public ServiceFuture createAsync(String personGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(personGroupId), serviceCallback); } /** * Create a new person in a specified person group. * * @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 the observable to the Person object */ - public Observable createAsync(String personGroupId, CreatePersonGroupPersonsOptionalParameter createOptionalParameter) { - return createWithServiceResponseAsync(personGroupId, createOptionalParameter).map(new Func1, Person>() { + public Observable createAsync(String personGroupId) { + return createWithServiceResponseAsync(personGroupId).map(new Func1, Person>() { @Override public Person call(ServiceResponse response) { return response.body(); @@ -165,21 +156,81 @@ public Person call(ServiceResponse response) { * Create a new person in a specified person group. * * @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 the observable to the Person object */ - public Observable> createWithServiceResponseAsync(String personGroupId, CreatePersonGroupPersonsOptionalParameter createOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> createWithServiceResponseAsync(String personGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - final String name = createOptionalParameter != null ? createOptionalParameter.name() : null; - final String userData = createOptionalParameter != null ? createOptionalParameter.userData() : null; + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(personGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Create a new person in a specified person group. + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 Person object if successful. + */ + public Person create(String personGroupId, String name, String userData) { + return createWithServiceResponseAsync(personGroupId, name, userData).toBlocking().single().body(); + } + + /** + * Create a new person in a specified person group. + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String personGroupId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(personGroupId, name, userData), serviceCallback); + } - return createWithServiceResponseAsync(personGroupId, name, userData); + /** + * Create a new person in a specified person group. + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Person object + */ + public Observable createAsync(String personGroupId, String name, String userData) { + return createWithServiceResponseAsync(personGroupId, name, userData).map(new Func1, Person>() { + @Override + public Person call(ServiceResponse response) { + return response.body(); + } + }); } /** @@ -192,17 +243,17 @@ public Observable> createWithServiceResponseAsync(String * @return the observable to the Person object */ public Observable> createWithServiceResponseAsync(String personGroupId, String name, String userData) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - NameAndUserDataContract bodyParameter = new NameAndUserDataContract(); - bodyParameter.withName(name); - bodyParameter.withUserData(userData); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.create(personGroupId, this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(personGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -223,100 +274,40 @@ private ServiceResponse createDelegate(Response response) .build(response); } - @Override - public PersonGroupPersonsCreateParameters create() { - return new PersonGroupPersonsCreateParameters(this); - } - - /** - * Internal class implementing PersonGroupPersonsCreateDefinition. - */ - class PersonGroupPersonsCreateParameters implements PersonGroupPersonsCreateDefinition { - private PersonGroupPersonsImpl parent; - private String personGroupId; - private String name; - private String userData; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupPersonsCreateParameters(PersonGroupPersonsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupPersonsCreateParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupPersonsCreateParameters withName(String name) { - this.name = name; - return this; - } - - @Override - public PersonGroupPersonsCreateParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public Person execute() { - return createWithServiceResponseAsync(personGroupId, name, userData).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return createWithServiceResponseAsync(personGroupId, name, userData).map(new Func1, Person>() { - @Override - public Person call(ServiceResponse response) { - return response.body(); - } - }); - } - } - - /** * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). * * @param personGroupId Id referencing a particular person group. - * @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<Person> object if successful. */ - public List list(String personGroupId, ListPersonGroupPersonsOptionalParameter listOptionalParameter) { - return listWithServiceResponseAsync(personGroupId, listOptionalParameter).toBlocking().single().body(); + public List list(String personGroupId) { + return listWithServiceResponseAsync(personGroupId).toBlocking().single().body(); } /** * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). * * @param personGroupId Id referencing a particular person group. - * @param listOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture> listAsync(String personGroupId, ListPersonGroupPersonsOptionalParameter listOptionalParameter, final ServiceCallback> serviceCallback) { - return ServiceFuture.fromResponse(listWithServiceResponseAsync(personGroupId, listOptionalParameter), serviceCallback); + public ServiceFuture> listAsync(String personGroupId, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(personGroupId), serviceCallback); } /** * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). * * @param personGroupId Id referencing a particular person group. - * @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<Person> object */ - public Observable> listAsync(String personGroupId, ListPersonGroupPersonsOptionalParameter listOptionalParameter) { - return listWithServiceResponseAsync(personGroupId, listOptionalParameter).map(new Func1>, List>() { + public Observable> listAsync(String personGroupId) { + return listWithServiceResponseAsync(personGroupId).map(new Func1>, List>() { @Override public List call(ServiceResponse> response) { return response.body(); @@ -328,21 +319,78 @@ public List call(ServiceResponse> response) { * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). * * @param personGroupId Id referencing a particular person group. - * @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<Person> object */ - public Observable>> listWithServiceResponseAsync(String personGroupId, ListPersonGroupPersonsOptionalParameter listOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable>> listWithServiceResponseAsync(String personGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - final String start = listOptionalParameter != null ? listOptionalParameter.start() : null; - final Integer top = listOptionalParameter != null ? listOptionalParameter.top() : null; + final String start = null; + final Integer top = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(personGroupId, start, top, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return listWithServiceResponseAsync(personGroupId, start, top); + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @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<Person> object if successful. + */ + public List list(String personGroupId, String start, Integer top) { + return listWithServiceResponseAsync(personGroupId, start, top).toBlocking().single().body(); + } + + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(String personGroupId, String start, Integer top, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(personGroupId, start, top), serviceCallback); + } + + /** + * List all persons in a person group, and retrieve person information (including personId, name, userData and persistedFaceIds of registered faces of the person). + * + * @param personGroupId Id referencing a particular person group. + * @param start Starting person id to return (used to list a range of persons). + * @param top Number of persons to return starting with the person id indicated by the 'start' parameter. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Person> object + */ + public Observable> listAsync(String personGroupId, String start, Integer top) { + return listWithServiceResponseAsync(personGroupId, start, top).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); } /** @@ -355,13 +403,13 @@ public Observable>> listWithServiceResponseAsync(St * @return the observable to the List<Person> object */ public Observable>> listWithServiceResponseAsync(String personGroupId, String start, Integer top) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.list(personGroupId, start, top, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>>() { @Override @@ -383,64 +431,8 @@ private ServiceResponse> listDelegate(Response respon .build(response); } - @Override - public PersonGroupPersonsListParameters list() { - return new PersonGroupPersonsListParameters(this); - } - - /** - * Internal class implementing PersonGroupPersonsListDefinition. - */ - class PersonGroupPersonsListParameters implements PersonGroupPersonsListDefinition { - private PersonGroupPersonsImpl parent; - private String personGroupId; - private String start; - private Integer top; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupPersonsListParameters(PersonGroupPersonsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupPersonsListParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupPersonsListParameters withStart(String start) { - this.start = start; - return this; - } - - @Override - public PersonGroupPersonsListParameters withTop(Integer top) { - this.top = top; - return this; - } - - @Override - public List execute() { - return listWithServiceResponseAsync(personGroupId, start, top).toBlocking().single().body(); - } - - @Override - public Observable> executeAsync() { - return listWithServiceResponseAsync(personGroupId, start, top).map(new Func1>, List>() { - @Override - public List call(ServiceResponse> response) { - return response.body(); - } - }); - } - } - /** - * Delete an existing person from a person group. Persisted face images of the person will also be deleted. + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -453,7 +445,7 @@ public void delete(String personGroupId, UUID personId) { } /** - * Delete an existing person from a person group. Persisted face images of the person will also be deleted. + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -466,7 +458,7 @@ public ServiceFuture deleteAsync(String personGroupId, UUID personId, fina } /** - * Delete an existing person from a person group. Persisted face images of the person will also be deleted. + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -483,7 +475,7 @@ public Void call(ServiceResponse response) { } /** - * Delete an existing person from a person group. Persisted face images of the person will also be deleted. + * Delete an existing person from a person group. The persistedFaceId, userData, person name and face feature in the person entry will all be deleted. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -491,8 +483,8 @@ public Void call(ServiceResponse response) { * @return the {@link ServiceResponse} object if successful. */ public Observable> deleteWithServiceResponseAsync(String personGroupId, UUID personId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -500,7 +492,7 @@ public Observable> deleteWithServiceResponseAsync(String p if (personId == null) { throw new IllegalArgumentException("Parameter personId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.delete(personGroupId, personId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -575,8 +567,8 @@ public Person call(ServiceResponse response) { * @return the observable to the Person object */ public Observable> getWithServiceResponseAsync(String personGroupId, UUID personId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -584,7 +576,7 @@ public Observable> getWithServiceResponseAsync(String pe if (personId == null) { throw new IllegalArgumentException("Parameter personId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.get(personGroupId, personId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -606,19 +598,17 @@ private ServiceResponse getDelegate(Response response) thr .build(response); } - /** * Update name or userData of a person. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. - * @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 */ - public void update(String personGroupId, UUID personId, UpdatePersonGroupPersonsOptionalParameter updateOptionalParameter) { - updateWithServiceResponseAsync(personGroupId, personId, updateOptionalParameter).toBlocking().single().body(); + public void update(String personGroupId, UUID personId) { + updateWithServiceResponseAsync(personGroupId, personId).toBlocking().single().body(); } /** @@ -626,13 +616,12 @@ public void update(String personGroupId, UUID personId, UpdatePersonGroupPersons * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture updateAsync(String personGroupId, UUID personId, UpdatePersonGroupPersonsOptionalParameter updateOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(updateWithServiceResponseAsync(personGroupId, personId, updateOptionalParameter), serviceCallback); + public ServiceFuture updateAsync(String personGroupId, UUID personId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(personGroupId, personId), serviceCallback); } /** @@ -640,12 +629,11 @@ public ServiceFuture updateAsync(String personGroupId, UUID personId, Upda * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable updateAsync(String personGroupId, UUID personId, UpdatePersonGroupPersonsOptionalParameter updateOptionalParameter) { - return updateWithServiceResponseAsync(personGroupId, personId, updateOptionalParameter).map(new Func1, Void>() { + public Observable updateAsync(String personGroupId, UUID personId) { + return updateWithServiceResponseAsync(personGroupId, personId).map(new Func1, Void>() { @Override public Void call(ServiceResponse response) { return response.body(); @@ -658,13 +646,12 @@ public Void call(ServiceResponse response) { * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. - * @param updateOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable> updateWithServiceResponseAsync(String personGroupId, UUID personId, UpdatePersonGroupPersonsOptionalParameter updateOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> updateWithServiceResponseAsync(String personGroupId, UUID personId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -672,10 +659,73 @@ public Observable> updateWithServiceResponseAsync(String p if (personId == null) { throw new IllegalArgumentException("Parameter personId is required and cannot be null."); } - final String name = updateOptionalParameter != null ? updateOptionalParameter.name() : null; - final String userData = updateOptionalParameter != null ? updateOptionalParameter.userData() : null; + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(personGroupId, personId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return updateWithServiceResponseAsync(personGroupId, personId, name, userData); + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 + */ + public void update(String personGroupId, UUID personId, String name, String userData) { + updateWithServiceResponseAsync(personGroupId, personId, name, userData).toBlocking().single().body(); + } + + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String personGroupId, UUID personId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(personGroupId, personId, name, userData), serviceCallback); + } + + /** + * Update name or userData of a person. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String personGroupId, UUID personId, String name, String userData) { + return updateWithServiceResponseAsync(personGroupId, personId, name, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); } /** @@ -689,8 +739,8 @@ public Observable> updateWithServiceResponseAsync(String p * @return the {@link ServiceResponse} object if successful. */ public Observable> updateWithServiceResponseAsync(String personGroupId, UUID personId, String name, String userData) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -698,11 +748,11 @@ public Observable> updateWithServiceResponseAsync(String p if (personId == null) { throw new IllegalArgumentException("Parameter personId is required and cannot be null."); } - NameAndUserDataContract bodyParameter = new NameAndUserDataContract(); - bodyParameter.withName(name); - bodyParameter.withUserData(userData); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.update(personGroupId, personId, this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(personGroupId, personId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -723,71 +773,9 @@ private ServiceResponse updateDelegate(Response response) th .build(response); } - @Override - public PersonGroupPersonsUpdateParameters update() { - return new PersonGroupPersonsUpdateParameters(this); - } - /** - * Internal class implementing PersonGroupPersonsUpdateDefinition. - */ - class PersonGroupPersonsUpdateParameters implements PersonGroupPersonsUpdateDefinition { - private PersonGroupPersonsImpl parent; - private String personGroupId; - private UUID personId; - private String name; - private String userData; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupPersonsUpdateParameters(PersonGroupPersonsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupPersonsUpdateParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupPersonsUpdateParameters withPersonId(UUID personId) { - this.personId = personId; - return this; - } - - @Override - public PersonGroupPersonsUpdateParameters withName(String name) { - this.name = name; - return this; - } - - @Override - public PersonGroupPersonsUpdateParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public void execute() { - updateWithServiceResponseAsync(personGroupId, personId, name, userData).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return updateWithServiceResponseAsync(personGroupId, personId, name, userData).map(new Func1, Void>() { - @Override - public Void call(ServiceResponse response) { - return response.body(); - } - }); - } - } - - /** - * Delete a face from a person. Relative image for the persisted face will also be deleted. + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -801,7 +789,8 @@ public void deleteFace(String personGroupId, UUID personId, UUID persistedFaceId } /** - * Delete a face from a person. Relative image for the persisted face will also be deleted. + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -815,7 +804,8 @@ public ServiceFuture deleteFaceAsync(String personGroupId, UUID personId, } /** - * Delete a face from a person. Relative image for the persisted face will also be deleted. + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -833,7 +823,8 @@ public Void call(ServiceResponse response) { } /** - * Delete a face from a person. Relative image for the persisted face will also be deleted. + * Delete a face from a person in a person group by specified personGroupId, personId and persistedFaceId. + <br /> Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -842,8 +833,8 @@ public Void call(ServiceResponse response) { * @return the {@link ServiceResponse} object if successful. */ public Observable> deleteFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -854,7 +845,7 @@ public Observable> deleteFaceWithServiceResponseAsync(Stri if (persistedFaceId == null) { throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.deleteFace(personGroupId, personId, persistedFaceId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -933,8 +924,8 @@ public PersistedFace call(ServiceResponse response) { * @return the observable to the PersistedFace object */ public Observable> getFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -945,7 +936,7 @@ public Observable> getFaceWithServiceResponseAsyn if (persistedFaceId == null) { throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.getFace(personGroupId, personId, persistedFaceId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -967,49 +958,66 @@ private ServiceResponse getFaceDelegate(Response re .build(response); } - /** - * Update a person persisted face's userData field. + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. - * @param updateFaceOptionalParameter 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 */ - public void updateFace(String personGroupId, UUID personId, UUID persistedFaceId, UpdateFaceOptionalParameter updateFaceOptionalParameter) { - updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, updateFaceOptionalParameter).toBlocking().single().body(); + public void updateFace(String personGroupId, UUID personId, UUID persistedFaceId) { + updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId).toBlocking().single().body(); } /** - * Update a person persisted face's userData field. + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. - * @param updateFaceOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, UpdateFaceOptionalParameter updateFaceOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, updateFaceOptionalParameter), serviceCallback); + public ServiceFuture updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId), serviceCallback); } /** - * Update a person persisted face's userData field. + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. - * @param updateFaceOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, UpdateFaceOptionalParameter updateFaceOptionalParameter) { - return updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, updateFaceOptionalParameter).map(new Func1, Void>() { + public Observable updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId) { + return updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId).map(new Func1, Void>() { @Override public Void call(ServiceResponse response) { return response.body(); @@ -1018,18 +1026,24 @@ public Void call(ServiceResponse response) { } /** - * Update a person persisted face's userData field. + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. - * @param updateFaceOptionalParameter the object representing the optional parameters to be set before calling this API * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable> updateFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId, UpdateFaceOptionalParameter updateFaceOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> updateFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -1040,13 +1054,103 @@ public Observable> updateFaceWithServiceResponseAsync(Stri if (persistedFaceId == null) { throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); } - final String userData = updateFaceOptionalParameter != null ? updateFaceOptionalParameter.userData() : null; + final String userData = null; + UpdateFaceRequest body = new UpdateFaceRequest(); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.updateFace(personGroupId, personId, persistedFaceId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateFaceDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @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 + */ + public void updateFace(String personGroupId, UUID personId, UUID persistedFaceId, String userData) { + updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, userData).toBlocking().single().body(); + } + + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, userData), serviceCallback); + } - return updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, userData); + /** + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param persistedFaceId Id referencing a particular persistedFaceId of an existing face. + * @param userData User-provided data attached to the face. The size limit is 1KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateFaceAsync(String personGroupId, UUID personId, UUID persistedFaceId, String userData) { + return updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); } /** - * Update a person persisted face's userData field. + * Add a face to a person into a person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [PersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e), [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -1056,8 +1160,8 @@ public Observable> updateFaceWithServiceResponseAsync(Stri * @return the {@link ServiceResponse} object if successful. */ public Observable> updateFaceWithServiceResponseAsync(String personGroupId, UUID personId, UUID persistedFaceId, String userData) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -1068,10 +1172,10 @@ public Observable> updateFaceWithServiceResponseAsync(Stri if (persistedFaceId == null) { throw new IllegalArgumentException("Parameter persistedFaceId is required and cannot be null."); } - UpdatePersonFaceRequest bodyParameter = new UpdatePersonFaceRequest(); - bodyParameter.withUserData(userData); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.updateFace(personGroupId, personId, persistedFaceId, this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + UpdateFaceRequest body = new UpdateFaceRequest(); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.updateFace(personGroupId, personId, persistedFaceId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -1092,113 +1196,67 @@ private ServiceResponse updateFaceDelegate(Response response .build(response); } - @Override - public PersonGroupPersonsUpdateFaceParameters updateFace() { - return new PersonGroupPersonsUpdateFaceParameters(this); - } - /** - * Internal class implementing PersonGroupPersonsUpdateFaceDefinition. - */ - class PersonGroupPersonsUpdateFaceParameters implements PersonGroupPersonsUpdateFaceDefinition { - private PersonGroupPersonsImpl parent; - private String personGroupId; - private UUID personId; - private UUID persistedFaceId; - private String userData; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupPersonsUpdateFaceParameters(PersonGroupPersonsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupPersonsUpdateFaceParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupPersonsUpdateFaceParameters withPersonId(UUID personId) { - this.personId = personId; - return this; - } - - @Override - public PersonGroupPersonsUpdateFaceParameters withPersistedFaceId(UUID persistedFaceId) { - this.persistedFaceId = persistedFaceId; - return this; - } - - @Override - public PersonGroupPersonsUpdateFaceParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public void execute() { - updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, userData).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return updateFaceWithServiceResponseAsync(personGroupId, personId, persistedFaceId, userData).map(new Func1, Void>() { - @Override - public Void call(ServiceResponse response) { - return response.body(); - } - }); - } - } - - - /** - * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param url Publicly reachable URL of an image - * @param addPersonFaceFromUrlOptionalParameter 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 PersistedFace object if successful. */ - public PersistedFace addPersonFaceFromUrl(String personGroupId, UUID personId, String url, AddPersonFaceFromUrlOptionalParameter addPersonFaceFromUrlOptionalParameter) { - return addPersonFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, addPersonFaceFromUrlOptionalParameter).toBlocking().single().body(); + public PersistedFace addFaceFromUrl(String personGroupId, UUID personId, String url) { + return addFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url).toBlocking().single().body(); } /** - * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param url Publicly reachable URL of an image - * @param addPersonFaceFromUrlOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture addPersonFaceFromUrlAsync(String personGroupId, UUID personId, String url, AddPersonFaceFromUrlOptionalParameter addPersonFaceFromUrlOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(addPersonFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, addPersonFaceFromUrlOptionalParameter), serviceCallback); + public ServiceFuture addFaceFromUrlAsync(String personGroupId, UUID personId, String url, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url), serviceCallback); } /** - * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param url Publicly reachable URL of an image - * @param addPersonFaceFromUrlOptionalParameter 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 PersistedFace object */ - public Observable addPersonFaceFromUrlAsync(String personGroupId, UUID personId, String url, AddPersonFaceFromUrlOptionalParameter addPersonFaceFromUrlOptionalParameter) { - return addPersonFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, addPersonFaceFromUrlOptionalParameter).map(new Func1, PersistedFace>() { + public Observable addFaceFromUrlAsync(String personGroupId, UUID personId, String url) { + return addFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url).map(new Func1, PersistedFace>() { @Override public PersistedFace call(ServiceResponse response) { return response.body(); @@ -1207,18 +1265,24 @@ public PersistedFace call(ServiceResponse response) { } /** - * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param url Publicly reachable URL of an image - * @param addPersonFaceFromUrlOptionalParameter 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 PersistedFace object */ - public Observable> addPersonFaceFromUrlWithServiceResponseAsync(String personGroupId, UUID personId, String url, AddPersonFaceFromUrlOptionalParameter addPersonFaceFromUrlOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> addFaceFromUrlWithServiceResponseAsync(String personGroupId, UUID personId, String url) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -1229,14 +1293,109 @@ public Observable> addPersonFaceFromUrlWithServic if (url == null) { throw new IllegalArgumentException("Parameter url is required and cannot be null."); } - final String userData = addPersonFaceFromUrlOptionalParameter != null ? addPersonFaceFromUrlOptionalParameter.userData() : null; - final List targetFace = addPersonFaceFromUrlOptionalParameter != null ? addPersonFaceFromUrlOptionalParameter.targetFace() : null; + final String userData = null; + final List targetFace = null; + ImageUrl imageUrl = new ImageUrl(); + imageUrl.withUrl(url); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); + return service.addFaceFromUrl(personGroupId, personId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromUrlDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return addPersonFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, userData, targetFace); + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromUrl(String personGroupId, UUID personId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, userData, targetFace).toBlocking().single().body(); } /** - * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromUrlAsync(String personGroupId, UUID personId, String url, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, userData, targetFace), serviceCallback); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param url Publicly reachable URL of an image + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable addFaceFromUrlAsync(String personGroupId, UUID personId, String url, String userData, List targetFace) { + return addFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a face to a person into a large person group for face identification or verification. To deal with an image contains multiple faces, input face can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. No image will be stored. Only the extracted face feature will be stored on server until [LargePersonGroup PersonFace - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3), [LargePersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or [LargePersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called. + <br /> Note persistedFaceId is different from faceId generated by [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236). + * Higher face image quality means better recognition precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger. + * Each person entry can hold up to 248 faces. + * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. + * "targetFace" rectangle should contain one face. Zero or multiple faces will be regarded as an error. If the provided "targetFace" rectangle is not returned from [Face - Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), there’s no guarantee to detect and add the face successfully. + * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose, or large occlusions will cause failures. + * Adding/deleting faces to/from a same person will be processed sequentially. Adding/deleting faces to/from different persons are processed in parallel. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. @@ -1246,9 +1405,9 @@ public Observable> addPersonFaceFromUrlWithServic * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the PersistedFace object */ - public Observable> addPersonFaceFromUrlWithServiceResponseAsync(String personGroupId, UUID personId, String url, String userData, List targetFace) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> addFaceFromUrlWithServiceResponseAsync(String personGroupId, UUID personId, String url, String userData, List targetFace) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -1262,14 +1421,14 @@ public Observable> addPersonFaceFromUrlWithServic Validator.validate(targetFace); ImageUrl imageUrl = new ImageUrl(); imageUrl.withUrl(url); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); - return service.addPersonFaceFromUrl(personGroupId, personId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) + return service.addFaceFromUrl(personGroupId, personId, userData, targetFaceConverted, this.client.acceptLanguage(), imageUrl, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { try { - ServiceResponse clientResponse = addPersonFaceFromUrlDelegate(response); + ServiceResponse clientResponse = addFaceFromUrlDelegate(response); return Observable.just(clientResponse); } catch (Throwable t) { return Observable.error(t); @@ -1278,98 +1437,26 @@ public Observable> call(Response re }); } - private ServiceResponse addPersonFaceFromUrlDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + private ServiceResponse addFaceFromUrlDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) .register(200, new TypeToken() { }.getType()) .registerError(APIErrorException.class) .build(response); } - @Override - public PersonGroupPersonsAddPersonFaceFromUrlParameters addPersonFaceFromUrl() { - return new PersonGroupPersonsAddPersonFaceFromUrlParameters(this); - } - - /** - * Internal class implementing PersonGroupPersonsAddPersonFaceFromUrlDefinition. - */ - class PersonGroupPersonsAddPersonFaceFromUrlParameters implements PersonGroupPersonsAddPersonFaceFromUrlDefinition { - private PersonGroupPersonsImpl parent; - private String personGroupId; - private UUID personId; - private String url; - private String userData; - private List targetFace; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupPersonsAddPersonFaceFromUrlParameters(PersonGroupPersonsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromUrlParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromUrlParameters withPersonId(UUID personId) { - this.personId = personId; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromUrlParameters withUrl(String url) { - this.url = url; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromUrlParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromUrlParameters withTargetFace(List targetFace) { - this.targetFace = targetFace; - return this; - } - - @Override - public PersistedFace execute() { - return addPersonFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, userData, targetFace).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return addPersonFaceFromUrlWithServiceResponseAsync(personGroupId, personId, url, userData, targetFace).map(new Func1, PersistedFace>() { - @Override - public PersistedFace call(ServiceResponse response) { - return response.body(); - } - }); - } - } - - /** * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. * * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param image An image stream. - * @param addPersonFaceFromStreamOptionalParameter 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 PersistedFace object if successful. */ - public PersistedFace addPersonFaceFromStream(String personGroupId, UUID personId, byte[] image, AddPersonFaceFromStreamOptionalParameter addPersonFaceFromStreamOptionalParameter) { - return addPersonFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, addPersonFaceFromStreamOptionalParameter).toBlocking().single().body(); + public PersistedFace addFaceFromStream(String personGroupId, UUID personId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image).toBlocking().single().body(); } /** @@ -1378,13 +1465,12 @@ public PersistedFace addPersonFaceFromStream(String personGroupId, UUID personId * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param image An image stream. - * @param addPersonFaceFromStreamOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture addPersonFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, AddPersonFaceFromStreamOptionalParameter addPersonFaceFromStreamOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(addPersonFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, addPersonFaceFromStreamOptionalParameter), serviceCallback); + public ServiceFuture addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image), serviceCallback); } /** @@ -1393,12 +1479,11 @@ public ServiceFuture addPersonFaceFromStreamAsync(String personGr * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param image An image stream. - * @param addPersonFaceFromStreamOptionalParameter 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 PersistedFace object */ - public Observable addPersonFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, AddPersonFaceFromStreamOptionalParameter addPersonFaceFromStreamOptionalParameter) { - return addPersonFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, addPersonFaceFromStreamOptionalParameter).map(new Func1, PersistedFace>() { + public Observable addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image) { + return addFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image).map(new Func1, PersistedFace>() { @Override public PersistedFace call(ServiceResponse response) { return response.body(); @@ -1412,13 +1497,12 @@ public PersistedFace call(ServiceResponse response) { * @param personGroupId Id referencing a particular person group. * @param personId Id referencing a particular person. * @param image An image stream. - * @param addPersonFaceFromStreamOptionalParameter 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 PersistedFace object */ - public Observable> addPersonFaceFromStreamWithServiceResponseAsync(String personGroupId, UUID personId, byte[] image, AddPersonFaceFromStreamOptionalParameter addPersonFaceFromStreamOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> addFaceFromStreamWithServiceResponseAsync(String personGroupId, UUID personId, byte[] image) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -1429,10 +1513,55 @@ public Observable> addPersonFaceFromStreamWithSer if (image == null) { throw new IllegalArgumentException("Parameter image is required and cannot be null."); } - final String userData = addPersonFaceFromStreamOptionalParameter != null ? addPersonFaceFromStreamOptionalParameter.userData() : null; - final List targetFace = addPersonFaceFromStreamOptionalParameter != null ? addPersonFaceFromStreamOptionalParameter.targetFace() : null; + final String userData = null; + final List targetFace = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.addFaceFromStream(personGroupId, personId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = addFaceFromStreamDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return addPersonFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, userData, targetFace); + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @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 PersistedFace object if successful. + */ + public PersistedFace addFaceFromStream(String personGroupId, UUID personId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, userData, targetFace).toBlocking().single().body(); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, String userData, List targetFace, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(addFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, userData, targetFace), serviceCallback); } /** @@ -1446,9 +1575,29 @@ public Observable> addPersonFaceFromStreamWithSer * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the PersistedFace object */ - public Observable> addPersonFaceFromStreamWithServiceResponseAsync(String personGroupId, UUID personId, byte[] image, String userData, List targetFace) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable addFaceFromStreamAsync(String personGroupId, UUID personId, byte[] image, String userData, List targetFace) { + return addFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, userData, targetFace).map(new Func1, PersistedFace>() { + @Override + public PersistedFace call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Add a representative face to a person for identification. The input face is specified as an image with a targetFace rectangle. + * + * @param personGroupId Id referencing a particular person group. + * @param personId Id referencing a particular person. + * @param image An image stream. + * @param userData User-specified data about the face for any purpose. The maximum length is 1KB. + * @param targetFace A face rectangle to specify the target face to be added to a person in the format of "targetFace=left,top,width,height". E.g. "targetFace=10,10,100,100". If there is more than one face in the image, targetFace is required to specify which face to add. No targetFace means there is only one face detected in the entire image. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersistedFace object + */ + public Observable> addFaceFromStreamWithServiceResponseAsync(String personGroupId, UUID personId, byte[] image, String userData, List targetFace) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); @@ -1460,15 +1609,14 @@ public Observable> addPersonFaceFromStreamWithSer throw new IllegalArgumentException("Parameter image is required and cannot be null."); } Validator.validate(targetFace); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV); - RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); - return service.addPersonFaceFromStream(personGroupId, personId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String targetFaceConverted = this.client.serializerAdapter().serializeList(targetFace, CollectionFormat.CSV);RequestBody imageConverted = RequestBody.create(MediaType.parse("application/octet-stream"), image); + return service.addFaceFromStream(personGroupId, personId, userData, targetFaceConverted, imageConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { try { - ServiceResponse clientResponse = addPersonFaceFromStreamDelegate(response); + ServiceResponse clientResponse = addFaceFromStreamDelegate(response); return Observable.just(clientResponse); } catch (Throwable t) { return Observable.error(t); @@ -1477,81 +1625,11 @@ public Observable> call(Response re }); } - private ServiceResponse addPersonFaceFromStreamDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + private ServiceResponse addFaceFromStreamDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) .register(200, new TypeToken() { }.getType()) .registerError(APIErrorException.class) .build(response); } - @Override - public PersonGroupPersonsAddPersonFaceFromStreamParameters addPersonFaceFromStream() { - return new PersonGroupPersonsAddPersonFaceFromStreamParameters(this); - } - - /** - * Internal class implementing PersonGroupPersonsAddPersonFaceFromStreamDefinition. - */ - class PersonGroupPersonsAddPersonFaceFromStreamParameters implements PersonGroupPersonsAddPersonFaceFromStreamDefinition { - private PersonGroupPersonsImpl parent; - private String personGroupId; - private UUID personId; - private byte[] image; - private String userData; - private List targetFace; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupPersonsAddPersonFaceFromStreamParameters(PersonGroupPersonsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromStreamParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromStreamParameters withPersonId(UUID personId) { - this.personId = personId; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromStreamParameters withImage(byte[] image) { - this.image = image; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromStreamParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public PersonGroupPersonsAddPersonFaceFromStreamParameters withTargetFace(List targetFace) { - this.targetFace = targetFace; - return this; - } - - @Override - public PersistedFace execute() { - return addPersonFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, userData, targetFace).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return addPersonFaceFromStreamWithServiceResponseAsync(personGroupId, personId, image, userData, targetFace).map(new Func1, PersistedFace>() { - @Override - public PersistedFace call(ServiceResponse response) { - return response.body(); - } - }); - } - } - } diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupsImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupsImpl.java index fe1eac104a0b..7bf0dc315257 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupsImpl.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/PersonGroupsImpl.java @@ -8,16 +8,15 @@ package com.microsoft.azure.cognitiveservices.vision.faceapi.implementation; -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 retrofit2.Retrofit; import com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups; import com.google.common.base.Joiner; import com.google.common.reflect.TypeToken; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.MetaDataContract; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.NameAndUserDataContract; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.PersonGroup; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.RecognitionModel; import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TrainingStatus; import com.microsoft.rest.ServiceCallback; import com.microsoft.rest.ServiceFuture; @@ -47,7 +46,7 @@ public class PersonGroupsImpl implements PersonGroups { /** The Retrofit service to perform REST calls. */ private PersonGroupsService service; /** The service client containing this operation class. */ - private FaceAPIImpl client; + private FaceClientImpl client; /** * Initializes an instance of PersonGroupsImpl. @@ -55,7 +54,7 @@ public class PersonGroupsImpl implements PersonGroups { * @param retrofit the Retrofit instance built from a Retrofit Builder. * @param client the instance of the service client containing this operation class. */ - public PersonGroupsImpl(Retrofit retrofit, FaceAPIImpl client) { + public PersonGroupsImpl(Retrofit retrofit, FaceClientImpl client) { this.service = retrofit.create(PersonGroupsService.class); this.client = client; } @@ -67,7 +66,7 @@ public PersonGroupsImpl(Retrofit retrofit, FaceAPIImpl client) { interface PersonGroupsService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups create" }) @PUT("persongroups/{personGroupId}") - Observable> create(@Path("personGroupId") String personGroupId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> create(@Path("personGroupId") String personGroupId, @Header("accept-language") String acceptLanguage, @Body MetaDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups delete" }) @HTTP(path = "persongroups/{personGroupId}", method = "DELETE", hasBody = true) @@ -75,11 +74,11 @@ interface PersonGroupsService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups get" }) @GET("persongroups/{personGroupId}") - Observable> get(@Path("personGroupId") String personGroupId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> get(@Path("personGroupId") String personGroupId, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups update" }) @PATCH("persongroups/{personGroupId}") - Observable> update(@Path("personGroupId") String personGroupId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract bodyParameter, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> update(@Path("personGroupId") String personGroupId, @Header("accept-language") String acceptLanguage, @Body NameAndUserDataContract body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups getTrainingStatus" }) @GET("persongroups/{personGroupId}/training") @@ -87,7 +86,7 @@ interface PersonGroupsService { @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups list" }) @GET("persongroups") - Observable> list(@Query("start") String start, @Query("top") Integer top, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + Observable> list(@Query("start") String start, @Query("top") Integer top, @Query("returnRecognitionModel") Boolean returnRecognitionModel, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.PersonGroups train" }) @POST("persongroups/{personGroupId}/train") @@ -95,43 +94,69 @@ interface PersonGroupsService { } - /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * * @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 */ - public void create(String personGroupId, CreatePersonGroupsOptionalParameter createOptionalParameter) { - createWithServiceResponseAsync(personGroupId, createOptionalParameter).toBlocking().single().body(); + public void create(String personGroupId) { + createWithServiceResponseAsync(personGroupId).toBlocking().single().body(); } /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * * @param personGroupId Id referencing a particular person group. - * @param createOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture createAsync(String personGroupId, CreatePersonGroupsOptionalParameter createOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(createWithServiceResponseAsync(personGroupId, createOptionalParameter), serviceCallback); + public ServiceFuture createAsync(String personGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(personGroupId), serviceCallback); } /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * * @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 the {@link ServiceResponse} object if successful. */ - public Observable createAsync(String personGroupId, CreatePersonGroupsOptionalParameter createOptionalParameter) { - return createWithServiceResponseAsync(personGroupId, createOptionalParameter).map(new Func1, Void>() { + public Observable createAsync(String personGroupId) { + return createWithServiceResponseAsync(personGroupId).map(new Func1, Void>() { @Override public Void call(ServiceResponse response) { return response.body(); @@ -140,47 +165,163 @@ public Void call(ServiceResponse response) { } /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * * @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 the {@link ServiceResponse} object if successful. */ - public Observable> createWithServiceResponseAsync(String personGroupId, CreatePersonGroupsOptionalParameter createOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> createWithServiceResponseAsync(String personGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - final String name = createOptionalParameter != null ? createOptionalParameter.name() : null; - final String userData = createOptionalParameter != null ? createOptionalParameter.userData() : null; + final String name = null; + final String userData = null; + final RecognitionModel recognitionModel = null; + MetaDataContract body = new MetaDataContract(); + body.withName(null); + body.withUserData(null); + body.withRecognitionModel(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(personGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = createDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @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 + */ + public void create(String personGroupId, String name, String userData, RecognitionModel recognitionModel) { + createWithServiceResponseAsync(personGroupId, name, userData, recognitionModel).toBlocking().single().body(); + } + + /** + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture createAsync(String personGroupId, String name, String userData, RecognitionModel recognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(createWithServiceResponseAsync(personGroupId, name, userData, recognitionModel), serviceCallback); + } - return createWithServiceResponseAsync(personGroupId, name, userData); + /** + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). + * + * @param personGroupId Id referencing a particular person group. + * @param name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable createAsync(String personGroupId, String name, String userData, RecognitionModel recognitionModel) { + return createWithServiceResponseAsync(personGroupId, name, userData, recognitionModel).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); } /** - * Create a new person group with specified personGroupId, name and user-provided userData. + * Create a new person group with specified personGroupId, name, user-provided userData and recognitionModel. + <br /> A person group is the container of the uploaded person data, including face recognition features. + <br /> After creation, use [PersonGroup Person - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add persons into the group, and then call [PersonGroup - Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this group ready for [Face - Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + <br /> No image will be stored. Only the person's extracted face features and userData will be stored on server until [PersonGroup Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or [PersonGroup - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called. + <br/>'recognitionModel' should be specified to associate with this person group. The default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly specify the model you need in this parameter. New faces that are added to an existing person group will use the recognition model that's already associated with the collection. Existing face features in a person group can't be updated to features extracted by another version of recognition model. + * 'recognition_01': The default recognition model for [PersonGroup - Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those person groups created before 2019 March are bonded with this recognition model. + * 'recognition_02': Recognition model released in 2019 March. 'recognition_02' is recommended since its overall accuracy is improved compared with 'recognition_01'. + Person group quota: + * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons. + * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons. + * to handle larger scale face identification problem, please consider using [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). * * @param personGroupId Id referencing a particular person group. * @param name User defined name, maximum length is 128. * @param userData User specified data. Length should not exceed 16KB. + * @param recognitionModel Possible values include: 'recognition_01', 'recognition_02' * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceResponse} object if successful. */ - public Observable> createWithServiceResponseAsync(String personGroupId, String name, String userData) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> createWithServiceResponseAsync(String personGroupId, String name, String userData, RecognitionModel recognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - NameAndUserDataContract bodyParameter = new NameAndUserDataContract(); - bodyParameter.withName(name); - bodyParameter.withUserData(userData); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.create(personGroupId, this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + MetaDataContract body = new MetaDataContract(); + body.withName(name); + body.withUserData(userData); + body.withRecognitionModel(recognitionModel); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.create(personGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -201,64 +342,8 @@ private ServiceResponse createDelegate(Response response) th .build(response); } - @Override - public PersonGroupsCreateParameters create() { - return new PersonGroupsCreateParameters(this); - } - - /** - * Internal class implementing PersonGroupsCreateDefinition. - */ - class PersonGroupsCreateParameters implements PersonGroupsCreateDefinition { - private PersonGroupsImpl parent; - private String personGroupId; - private String name; - private String userData; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupsCreateParameters(PersonGroupsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupsCreateParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupsCreateParameters withName(String name) { - this.name = name; - return this; - } - - @Override - public PersonGroupsCreateParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public void execute() { - createWithServiceResponseAsync(personGroupId, name, userData).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return createWithServiceResponseAsync(personGroupId, name, userData).map(new Func1, Void>() { - @Override - public Void call(ServiceResponse response) { - return response.body(); - } - }); - } - } - /** - * Delete an existing person group. Persisted face images of all people in the person group will also be deleted. + * Delete an existing person group. Persisted face features 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 @@ -270,7 +355,7 @@ public void delete(String personGroupId) { } /** - * Delete an existing person group. Persisted face images of all people in the person group will also be deleted. + * Delete an existing person group. Persisted face features of all people in the person group will also be deleted. * * @param personGroupId Id referencing a particular person group. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. @@ -282,7 +367,7 @@ public ServiceFuture deleteAsync(String personGroupId, final ServiceCallba } /** - * Delete an existing person group. Persisted face images of all people in the person group will also be deleted. + * Delete an existing person group. Persisted face features 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 @@ -298,20 +383,20 @@ public Void call(ServiceResponse response) { } /** - * Delete an existing person group. Persisted face images of all people in the person group will also be deleted. + * Delete an existing person group. Persisted face features 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 the {@link ServiceResponse} object if successful. */ public Observable> deleteWithServiceResponseAsync(String personGroupId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.delete(personGroupId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -334,7 +419,7 @@ private ServiceResponse deleteDelegate(Response response) th } /** - * Retrieve the information of a person group, including its name and userData. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -347,7 +432,7 @@ public PersonGroup get(String personGroupId) { } /** - * Retrieve the information of a person group, including its name and userData. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. @@ -359,7 +444,7 @@ public ServiceFuture getAsync(String personGroupId, final ServiceCa } /** - * Retrieve the information of a person group, including its name and userData. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -375,21 +460,96 @@ public PersonGroup call(ServiceResponse response) { } /** - * Retrieve the information of a person group, including its name and userData. + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). * * @param personGroupId Id referencing a particular person group. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the PersonGroup object */ public Observable> getWithServiceResponseAsync(String personGroupId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (personGroupId == null) { + throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); + } + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(personGroupId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). + * + * @param personGroupId Id referencing a particular person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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. + */ + public PersonGroup get(String personGroupId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(personGroupId, returnRecognitionModel).toBlocking().single().body(); + } + + /** + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). + * + * @param personGroupId Id referencing a particular person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getAsync(String personGroupId, Boolean returnRecognitionModel, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(personGroupId, returnRecognitionModel), serviceCallback); + } + + /** + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). + * + * @param personGroupId Id referencing a particular person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersonGroup object + */ + public Observable getAsync(String personGroupId, Boolean returnRecognitionModel) { + return getWithServiceResponseAsync(personGroupId, returnRecognitionModel).map(new Func1, PersonGroup>() { + @Override + public PersonGroup call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve person group name, userData and recognitionModel. To get person information under this personGroup, use [PersonGroup Person - List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). + * + * @param personGroupId Id referencing a particular person group. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the PersonGroup object + */ + public Observable> getWithServiceResponseAsync(String personGroupId, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.get(personGroupId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(personGroupId, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -410,43 +570,39 @@ private ServiceResponse getDelegate(Response response .build(response); } - /** * 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 */ - public void update(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter) { - updateWithServiceResponseAsync(personGroupId, updateOptionalParameter).toBlocking().single().body(); + public void update(String personGroupId) { + updateWithServiceResponseAsync(personGroupId).toBlocking().single().body(); } /** * 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 * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture updateAsync(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter, final ServiceCallback serviceCallback) { - return ServiceFuture.fromResponse(updateWithServiceResponseAsync(personGroupId, updateOptionalParameter), serviceCallback); + public ServiceFuture updateAsync(String personGroupId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(personGroupId), serviceCallback); } /** * 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 the {@link ServiceResponse} object if successful. */ - public Observable updateAsync(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter) { - return updateWithServiceResponseAsync(personGroupId, updateOptionalParameter).map(new Func1, Void>() { + public Observable updateAsync(String personGroupId) { + return updateWithServiceResponseAsync(personGroupId).map(new Func1, Void>() { @Override public Void call(ServiceResponse response) { return response.body(); @@ -458,21 +614,80 @@ public Void call(ServiceResponse response) { * 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 the {@link ServiceResponse} object if successful. */ - public Observable> updateWithServiceResponseAsync(String personGroupId, UpdatePersonGroupsOptionalParameter updateOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> updateWithServiceResponseAsync(String personGroupId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - final String name = updateOptionalParameter != null ? updateOptionalParameter.name() : null; - final String userData = updateOptionalParameter != null ? updateOptionalParameter.userData() : null; + final String name = null; + final String userData = null; + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(personGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return updateWithServiceResponseAsync(personGroupId, name, userData); + /** + * 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 name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @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 + */ + public void update(String personGroupId, String name, String userData) { + updateWithServiceResponseAsync(personGroupId, name, userData).toBlocking().single().body(); + } + + /** + * 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 name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(String personGroupId, String name, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(personGroupId, name, userData), serviceCallback); + } + + /** + * 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 name User defined name, maximum length is 128. + * @param userData User specified data. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(String personGroupId, String name, String userData) { + return updateWithServiceResponseAsync(personGroupId, name, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); } /** @@ -485,17 +700,17 @@ public Observable> updateWithServiceResponseAsync(String p * @return the {@link ServiceResponse} object if successful. */ public Observable> updateWithServiceResponseAsync(String personGroupId, String name, String userData) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - NameAndUserDataContract bodyParameter = new NameAndUserDataContract(); - bodyParameter.withName(name); - bodyParameter.withUserData(userData); - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.update(personGroupId, this.client.acceptLanguage(), bodyParameter, parameterizedHost, this.client.userAgent()) + NameAndUserDataContract body = new NameAndUserDataContract(); + body.withName(name); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(personGroupId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override public Observable> call(Response response) { @@ -516,62 +731,6 @@ private ServiceResponse updateDelegate(Response response) th .build(response); } - @Override - public PersonGroupsUpdateParameters update() { - return new PersonGroupsUpdateParameters(this); - } - - /** - * Internal class implementing PersonGroupsUpdateDefinition. - */ - class PersonGroupsUpdateParameters implements PersonGroupsUpdateDefinition { - private PersonGroupsImpl parent; - private String personGroupId; - private String name; - private String userData; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupsUpdateParameters(PersonGroupsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupsUpdateParameters withPersonGroupId(String personGroupId) { - this.personGroupId = personGroupId; - return this; - } - - @Override - public PersonGroupsUpdateParameters withName(String name) { - this.name = name; - return this; - } - - @Override - public PersonGroupsUpdateParameters withUserData(String userData) { - this.userData = userData; - return this; - } - - @Override - public void execute() { - updateWithServiceResponseAsync(personGroupId, name, userData).toBlocking().single().body(); - } - - @Override - public Observable executeAsync() { - return updateWithServiceResponseAsync(personGroupId, name, userData).map(new Func1, Void>() { - @Override - public Void call(ServiceResponse response) { - return response.body(); - } - }); - } - } - /** * Retrieve the training status of a person group (completed or ongoing). * @@ -621,13 +780,13 @@ public TrainingStatus call(ServiceResponse response) { * @return the observable to the TrainingStatus object */ public Observable> getTrainingStatusWithServiceResponseAsync(String personGroupId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.getTrainingStatus(personGroupId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override @@ -649,41 +808,61 @@ private ServiceResponse getTrainingStatusDelegate(Response list(ListPersonGroupsOptionalParameter listOptionalParameter) { - return listWithServiceResponseAsync(listOptionalParameter).toBlocking().single().body(); + public List list() { + return listWithServiceResponseAsync().toBlocking().single().body(); } /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". * - * @param listOptionalParameter the object representing the optional parameters to be set before calling this API * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the {@link ServiceFuture} object */ - public ServiceFuture> listAsync(ListPersonGroupsOptionalParameter listOptionalParameter, final ServiceCallback> serviceCallback) { - return ServiceFuture.fromResponse(listWithServiceResponseAsync(listOptionalParameter), serviceCallback); + public ServiceFuture> listAsync(final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(), serviceCallback); } /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". * - * @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<PersonGroup> object */ - public Observable> listAsync(ListPersonGroupsOptionalParameter listOptionalParameter) { - return listWithServiceResponseAsync(listOptionalParameter).map(new Func1>, List>() { + public Observable> listAsync() { + return listWithServiceResponseAsync().map(new Func1>, List>() { @Override public List call(ServiceResponse> response) { return response.body(); @@ -692,36 +871,135 @@ public List call(ServiceResponse> response) { } /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". * - * @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<PersonGroup> object */ - public Observable>> listWithServiceResponseAsync(ListPersonGroupsOptionalParameter listOptionalParameter) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable>> listWithServiceResponseAsync() { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } - final String start = listOptionalParameter != null ? listOptionalParameter.start() : null; - final Integer top = listOptionalParameter != null ? listOptionalParameter.top() : null; + final String start = null; + final Integer top = null; + final Boolean returnRecognitionModel = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(start, top, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } - return listWithServiceResponseAsync(start, top); + /** + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List person groups from the least personGroupId greater than the "start". + * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @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<PersonGroup> object if successful. + */ + public List list(String start, Integer top, Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(start, top, returnRecognitionModel).toBlocking().single().body(); + } + + /** + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List person groups from the least personGroupId greater than the "start". + * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(String start, Integer top, Boolean returnRecognitionModel, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(start, top, returnRecognitionModel), serviceCallback); } /** - * List person groups and their information. + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". * * @param start List person groups from the least personGroupId greater than the "start". * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the List<PersonGroup> object */ - public Observable>> listWithServiceResponseAsync(String start, Integer top) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + public Observable> listAsync(String start, Integer top, Boolean returnRecognitionModel) { + return listWithServiceResponseAsync(start, top, returnRecognitionModel).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List person groups’ personGroupId, name, userData and recognitionModel.<br /> + * Person groups are stored in alphabetical order of personGroupId. + * "start" parameter (string, optional) is a user-provided personGroupId value that returned entries have larger ids by string comparison. "start" set to empty to indicate return from the first item. + * "top" parameter (int, optional) specifies the number of entries to return. A maximal of 1000 entries can be returned in one call. To fetch more, you can specify "start" with the last returned entry’s Id of the current call. + <br /> + For example, total 5 person groups: "group1", ..., "group5". + <br /> "start=&top=" will return all 5 groups. + <br /> "start=&top=2" will return "group1", "group2". + <br /> "start=group2&top=3" will return "group3", "group4", "group5". + * + * @param start List person groups from the least personGroupId greater than the "start". + * @param top The number of person groups to list. + * @param returnRecognitionModel A value indicating whether the operation should return 'recognitionModel' in response. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<PersonGroup> object + */ + public Observable>> listWithServiceResponseAsync(String start, Integer top, Boolean returnRecognitionModel) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); - return service.list(start, top, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.list(start, top, returnRecognitionModel, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>>() { @Override public Observable>> call(Response response) { @@ -742,55 +1020,6 @@ private ServiceResponse> listDelegate(Response r .build(response); } - @Override - public PersonGroupsListParameters list() { - return new PersonGroupsListParameters(this); - } - - /** - * Internal class implementing PersonGroupsListDefinition. - */ - class PersonGroupsListParameters implements PersonGroupsListDefinition { - private PersonGroupsImpl parent; - private String start; - private Integer top; - - /** - * Constructor. - * @param parent the parent object. - */ - PersonGroupsListParameters(PersonGroupsImpl parent) { - this.parent = parent; - } - - @Override - public PersonGroupsListParameters withStart(String start) { - this.start = start; - return this; - } - - @Override - public PersonGroupsListParameters withTop(Integer top) { - this.top = top; - return this; - } - - @Override - public List execute() { - return listWithServiceResponseAsync(start, top).toBlocking().single().body(); - } - - @Override - public Observable> executeAsync() { - return listWithServiceResponseAsync(start, top).map(new Func1>, List>() { - @Override - public List call(ServiceResponse> response) { - return response.body(); - } - }); - } - } - /** * Queue a person group training task, the training task may not be started immediately. * @@ -839,13 +1068,13 @@ public Void call(ServiceResponse response) { * @return the {@link ServiceResponse} object if successful. */ public Observable> trainWithServiceResponseAsync(String personGroupId) { - if (this.client.azureRegion() == null) { - throw new IllegalArgumentException("Parameter this.client.azureRegion() is required and cannot be null."); + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); } if (personGroupId == null) { throw new IllegalArgumentException("Parameter personGroupId is required and cannot be null."); } - String parameterizedHost = Joiner.on(", ").join("{AzureRegion}", this.client.azureRegion()); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); return service.train(personGroupId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) .flatMap(new Func1, Observable>>() { @Override diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/SnapshotsImpl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/SnapshotsImpl.java new file mode 100644 index 000000000000..29c06d6c4088 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/SnapshotsImpl.java @@ -0,0 +1,1122 @@ +/** + * 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.implementation; + +import retrofit2.Retrofit; +import com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots; +import com.google.common.base.Joiner; +import com.google.common.reflect.TypeToken; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.APIErrorException; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.ApplySnapshotRequest; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.OperationStatus; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.Snapshot; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotApplyHeaders; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotApplyMode; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotObjectType; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.SnapshotTakeHeaders; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.TakeSnapshotRequest; +import com.microsoft.azure.cognitiveservices.vision.faceapi.models.UpdateSnapshotRequest; +import com.microsoft.rest.CollectionFormat; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import com.microsoft.rest.ServiceResponseWithHeaders; +import com.microsoft.rest.Validator; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import okhttp3.ResponseBody; +import retrofit2.http.Body; +import retrofit2.http.GET; +import retrofit2.http.Header; +import retrofit2.http.Headers; +import retrofit2.http.HTTP; +import retrofit2.http.PATCH; +import retrofit2.http.Path; +import retrofit2.http.POST; +import retrofit2.http.Query; +import retrofit2.Response; +import rx.functions.Func1; +import rx.Observable; + +/** + * An instance of this class provides access to all the operations defined + * in Snapshots. + */ +public class SnapshotsImpl implements Snapshots { + /** The Retrofit service to perform REST calls. */ + private SnapshotsService service; + /** The service client containing this operation class. */ + private FaceClientImpl client; + + /** + * Initializes an instance of SnapshotsImpl. + * + * @param retrofit the Retrofit instance built from a Retrofit Builder. + * @param client the instance of the service client containing this operation class. + */ + public SnapshotsImpl(Retrofit retrofit, FaceClientImpl client) { + this.service = retrofit.create(SnapshotsService.class); + this.client = client; + } + + /** + * The interface defining all the services for Snapshots to be + * used by Retrofit to perform actually REST calls. + */ + interface SnapshotsService { + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots take" }) + @POST("snapshots") + Observable> take(@Header("accept-language") String acceptLanguage, @Body TakeSnapshotRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots list" }) + @GET("snapshots") + Observable> list(@Query("type") SnapshotObjectType type, @Query("applyScope") String applyScope, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots get" }) + @GET("snapshots/{snapshotId}") + Observable> get(@Path("snapshotId") UUID snapshotId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots update" }) + @PATCH("snapshots/{snapshotId}") + Observable> update(@Path("snapshotId") UUID snapshotId, @Header("accept-language") String acceptLanguage, @Body UpdateSnapshotRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots delete" }) + @HTTP(path = "snapshots/{snapshotId}", method = "DELETE", hasBody = true) + Observable> delete(@Path("snapshotId") UUID snapshotId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots apply" }) + @POST("snapshots/{snapshotId}/apply") + Observable> apply(@Path("snapshotId") UUID snapshotId, @Header("accept-language") String acceptLanguage, @Body ApplySnapshotRequest body, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.vision.faceapi.Snapshots getOperationStatus" }) + @GET("operations/{operationId}") + Observable> getOperationStatus(@Path("operationId") UUID operationId, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @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 + */ + public void take(SnapshotObjectType type, String objectId, List applyScope) { + takeWithServiceResponseAsync(type, objectId, applyScope).toBlocking().single().body(); + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture takeAsync(SnapshotObjectType type, String objectId, List applyScope, final ServiceCallback serviceCallback) { + return ServiceFuture.fromHeaderResponse(takeWithServiceResponseAsync(type, objectId, applyScope), serviceCallback); + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable takeAsync(SnapshotObjectType type, String objectId, List applyScope) { + return takeWithServiceResponseAsync(type, objectId, applyScope).map(new Func1, Void>() { + @Override + public Void call(ServiceResponseWithHeaders response) { + return response.body(); + } + }); + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable> takeWithServiceResponseAsync(SnapshotObjectType type, String objectId, List applyScope) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (type == null) { + throw new IllegalArgumentException("Parameter type is required and cannot be null."); + } + if (objectId == null) { + throw new IllegalArgumentException("Parameter objectId is required and cannot be null."); + } + if (applyScope == null) { + throw new IllegalArgumentException("Parameter applyScope is required and cannot be null."); + } + Validator.validate(applyScope); + final String userData = null; + TakeSnapshotRequest body = new TakeSnapshotRequest(); + body.withType(type); + body.withObjectId(objectId); + body.withApplyScope(applyScope); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.take(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponseWithHeaders clientResponse = takeDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @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 + */ + public void take(SnapshotObjectType type, String objectId, List applyScope, String userData) { + takeWithServiceResponseAsync(type, objectId, applyScope, userData).toBlocking().single().body(); + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture takeAsync(SnapshotObjectType type, String objectId, List applyScope, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromHeaderResponse(takeWithServiceResponseAsync(type, objectId, applyScope, userData), serviceCallback); + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable takeAsync(SnapshotObjectType type, String objectId, List applyScope, String userData) { + return takeWithServiceResponseAsync(type, objectId, applyScope, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponseWithHeaders response) { + return response.body(); + } + }); + } + + /** + * Submit an operation to take a snapshot of face list, large face list, person group or large person group, with user-specified snapshot type, source object id, apply scope and an optional user data.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Taking snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of creating the snapshot. The snapshot id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot taking time depends on the number of person and face entries in the source object. It could be in seconds, or up to several hours for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. User can delete the snapshot using Snapshot - Delete by themselves any time before expiration.<br /> + Taking snapshot for a certain object will not block any other operations against the object. All read-only operations (Get/List and Identify/FindSimilar/Verify) can be conducted as usual. For all writable operations, including Add/Update/Delete the source object or its persons/faces and Train, they are not blocked but not recommended because writable updates may not be reflected on the snapshot during its taking. After snapshot taking is completed, all readable and writable operations can work as normal. Snapshot will also include the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + * Free-tier subscription quota: 100 take operations per month. + * S0-tier subscription quota: 100 take operations per day. + * + * @param type User specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param objectId User specified source object id to take snapshot from. + * @param applyScope User specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable> takeWithServiceResponseAsync(SnapshotObjectType type, String objectId, List applyScope, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (type == null) { + throw new IllegalArgumentException("Parameter type is required and cannot be null."); + } + if (objectId == null) { + throw new IllegalArgumentException("Parameter objectId is required and cannot be null."); + } + if (applyScope == null) { + throw new IllegalArgumentException("Parameter applyScope is required and cannot be null."); + } + Validator.validate(applyScope); + TakeSnapshotRequest body = new TakeSnapshotRequest(); + body.withType(type); + body.withObjectId(objectId); + body.withApplyScope(applyScope); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.take(this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponseWithHeaders clientResponse = takeDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponseWithHeaders takeDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(202, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .buildWithHeaders(response, SnapshotTakeHeaders.class); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @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<Snapshot> object if successful. + */ + public List list() { + return listWithServiceResponseAsync().toBlocking().single().body(); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(), serviceCallback); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + public Observable> listAsync() { + return listWithServiceResponseAsync().map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + public Observable>> listWithServiceResponseAsync() { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + final SnapshotObjectType type = null; + final List applyScope = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String applyScopeConverted = this.client.serializerAdapter().serializeList(applyScope, CollectionFormat.CSV); + return service.list(type, applyScopeConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @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<Snapshot> object if successful. + */ + public List list(SnapshotObjectType type, List applyScope) { + return listWithServiceResponseAsync(type, applyScope).toBlocking().single().body(); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture> listAsync(SnapshotObjectType type, List applyScope, final ServiceCallback> serviceCallback) { + return ServiceFuture.fromResponse(listWithServiceResponseAsync(type, applyScope), serviceCallback); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + public Observable> listAsync(SnapshotObjectType type, List applyScope) { + return listWithServiceResponseAsync(type, applyScope).map(new Func1>, List>() { + @Override + public List call(ServiceResponse> response) { + return response.body(); + } + }); + } + + /** + * List all accessible snapshots with related information, including snapshots that were taken by the user, or snapshots to be applied to the user (subscription id was included in the applyScope in Snapshot - Take). + * + * @param type User specified object type as a search filter. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup' + * @param applyScope User specified snapshot apply scopes as a search filter. ApplyScope is an array of the target Azure subscription ids for the snapshot, specified by the user who created the snapshot by Snapshot - Take. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the List<Snapshot> object + */ + public Observable>> listWithServiceResponseAsync(SnapshotObjectType type, List applyScope) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + Validator.validate(applyScope); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + String applyScopeConverted = this.client.serializerAdapter().serializeList(applyScope, CollectionFormat.CSV); + return service.list(type, applyScopeConverted, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>>() { + @Override + public Observable>> call(Response response) { + try { + ServiceResponse> clientResponse = listDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse> listDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory()., APIErrorException>newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken>() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @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 Snapshot object if successful. + */ + public Snapshot get(UUID snapshotId) { + return getWithServiceResponseAsync(snapshotId).toBlocking().single().body(); + } + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getAsync(UUID snapshotId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getWithServiceResponseAsync(snapshotId), serviceCallback); + } + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Snapshot object + */ + public Observable getAsync(UUID snapshotId) { + return getWithServiceResponseAsync(snapshotId).map(new Func1, Snapshot>() { + @Override + public Snapshot call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve information about a snapshot. Snapshot is only accessible to the source subscription who took it, and target subscriptions included in the applyScope in Snapshot - Take. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the Snapshot object + */ + public Observable> getWithServiceResponseAsync(UUID snapshotId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (snapshotId == null) { + throw new IllegalArgumentException("Parameter snapshotId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.get(snapshotId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @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 + */ + public void update(UUID snapshotId) { + updateWithServiceResponseAsync(snapshotId).toBlocking().single().body(); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(UUID snapshotId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(snapshotId), serviceCallback); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(UUID snapshotId) { + return updateWithServiceResponseAsync(snapshotId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(UUID snapshotId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (snapshotId == null) { + throw new IllegalArgumentException("Parameter snapshotId is required and cannot be null."); + } + final List applyScope = null; + final String userData = null; + UpdateSnapshotRequest body = new UpdateSnapshotRequest(); + body.withApplyScope(null); + body.withUserData(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(snapshotId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @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 + */ + public void update(UUID snapshotId, List applyScope, String userData) { + updateWithServiceResponseAsync(snapshotId, applyScope, userData).toBlocking().single().body(); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture updateAsync(UUID snapshotId, List applyScope, String userData, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(updateWithServiceResponseAsync(snapshotId, applyScope, userData), serviceCallback); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable updateAsync(UUID snapshotId, List applyScope, String userData) { + return updateWithServiceResponseAsync(snapshotId, applyScope, userData).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Update the information of a snapshot. Only the source subscription who took the snapshot can update the snapshot. + * + * @param snapshotId Id referencing a particular snapshot. + * @param applyScope Array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * @param userData User specified data about the snapshot for any purpose. Length should not exceed 16KB. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> updateWithServiceResponseAsync(UUID snapshotId, List applyScope, String userData) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (snapshotId == null) { + throw new IllegalArgumentException("Parameter snapshotId is required and cannot be null."); + } + Validator.validate(applyScope); + UpdateSnapshotRequest body = new UpdateSnapshotRequest(); + body.withApplyScope(applyScope); + body.withUserData(userData); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.update(snapshotId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = updateDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse updateDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @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 + */ + public void delete(UUID snapshotId) { + deleteWithServiceResponseAsync(snapshotId).toBlocking().single().body(); + } + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteAsync(UUID snapshotId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteWithServiceResponseAsync(snapshotId), serviceCallback); + } + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteAsync(UUID snapshotId) { + return deleteWithServiceResponseAsync(snapshotId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete an existing snapshot according to the snapshotId. All object data and information in the snapshot will also be deleted. Only the source subscription who took the snapshot can delete the snapshot. If the user does not delete a snapshot with this API, the snapshot will still be automatically deleted in 48 hours after creation. + * + * @param snapshotId Id referencing a particular snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteWithServiceResponseAsync(UUID snapshotId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (snapshotId == null) { + throw new IllegalArgumentException("Parameter snapshotId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.delete(snapshotId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @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 + */ + public void apply(UUID snapshotId, String objectId) { + applyWithServiceResponseAsync(snapshotId, objectId).toBlocking().single().body(); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture applyAsync(UUID snapshotId, String objectId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromHeaderResponse(applyWithServiceResponseAsync(snapshotId, objectId), serviceCallback); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable applyAsync(UUID snapshotId, String objectId) { + return applyWithServiceResponseAsync(snapshotId, objectId).map(new Func1, Void>() { + @Override + public Void call(ServiceResponseWithHeaders response) { + return response.body(); + } + }); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable> applyWithServiceResponseAsync(UUID snapshotId, String objectId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (snapshotId == null) { + throw new IllegalArgumentException("Parameter snapshotId is required and cannot be null."); + } + if (objectId == null) { + throw new IllegalArgumentException("Parameter objectId is required and cannot be null."); + } + final SnapshotApplyMode mode = null; + ApplySnapshotRequest body = new ApplySnapshotRequest(); + body.withObjectId(objectId); + body.withMode(null); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.apply(snapshotId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponseWithHeaders clientResponse = applyDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @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 + */ + public void apply(UUID snapshotId, String objectId, SnapshotApplyMode mode) { + applyWithServiceResponseAsync(snapshotId, objectId, mode).toBlocking().single().body(); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture applyAsync(UUID snapshotId, String objectId, SnapshotApplyMode mode, final ServiceCallback serviceCallback) { + return ServiceFuture.fromHeaderResponse(applyWithServiceResponseAsync(snapshotId, objectId, mode), serviceCallback); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable applyAsync(UUID snapshotId, String objectId, SnapshotApplyMode mode) { + return applyWithServiceResponseAsync(snapshotId, objectId, mode).map(new Func1, Void>() { + @Override + public Void call(ServiceResponseWithHeaders response) { + return response.body(); + } + }); + } + + /** + * Submit an operation to apply a snapshot to current subscription. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it.<br /> + The snapshot interfaces are for users to backup and restore their face data from one face subscription to another, inside same region or across regions. The workflow contains two phases, user first calls Snapshot - Take to create a copy of the source object and store it as a snapshot, then calls Snapshot - Apply to paste the snapshot to target subscription. The snapshots are stored in a centralized location (per Azure instance), so that they can be applied cross accounts and regions.<br /> + Applying snapshot is an asynchronous operation. An operation id can be obtained from the "Operation-Location" field in response header, to be used in OperationStatus - Get for tracking the progress of applying the snapshot. The target object id will be included in the "resourceLocation" field in OperationStatus - Get response when the operation status is "succeeded".<br /> + Snapshot applying time depends on the number of person and face entries in the snapshot object. It could be in seconds, or up to 1 hour for 1,000,000 persons with multiple faces.<br /> + Snapshots will be automatically expired and cleaned in 48 hours after it is created by Snapshot - Take. So the target subscription is required to apply the snapshot in 48 hours since its creation.<br /> + Applying a snapshot will not block any other operations against the target object, however it is not recommended because the correctness cannot be guaranteed during snapshot applying. After snapshot applying is completed, all operations towards the target object can work as normal. Snapshot also includes the training results of the source object, which means target subscription the snapshot applied to does not need re-train the target object before calling Identify/FindSimilar.<br /> + One snapshot can be applied multiple times in parallel, while currently only CreateNew apply mode is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts.<br /> + * Free-tier subscription quota: 100 apply operations per month. + * S0-tier subscription quota: 100 apply operations per day. + * + * @param snapshotId Id referencing a particular snapshot. + * @param objectId User specified target object id to be created from the snapshot. + * @param mode Snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew' + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponseWithHeaders} object if successful. + */ + public Observable> applyWithServiceResponseAsync(UUID snapshotId, String objectId, SnapshotApplyMode mode) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (snapshotId == null) { + throw new IllegalArgumentException("Parameter snapshotId is required and cannot be null."); + } + if (objectId == null) { + throw new IllegalArgumentException("Parameter objectId is required and cannot be null."); + } + ApplySnapshotRequest body = new ApplySnapshotRequest(); + body.withObjectId(objectId); + body.withMode(mode); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.apply(snapshotId, this.client.acceptLanguage(), body, parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponseWithHeaders clientResponse = applyDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponseWithHeaders applyDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(202, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .buildWithHeaders(response, SnapshotApplyHeaders.class); + } + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @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 OperationStatus object if successful. + */ + public OperationStatus getOperationStatus(UUID operationId) { + return getOperationStatusWithServiceResponseAsync(operationId).toBlocking().single().body(); + } + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getOperationStatusAsync(UUID operationId, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getOperationStatusWithServiceResponseAsync(operationId), serviceCallback); + } + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the OperationStatus object + */ + public Observable getOperationStatusAsync(UUID operationId) { + return getOperationStatusWithServiceResponseAsync(operationId).map(new Func1, OperationStatus>() { + @Override + public OperationStatus call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Retrieve the status of a take/apply snapshot operation. + * + * @param operationId Id referencing a particular take/apply snapshot operation. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the OperationStatus object + */ + public Observable> getOperationStatusWithServiceResponseAsync(UUID operationId) { + if (this.client.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.client.endpoint() is required and cannot be null."); + } + if (operationId == null) { + throw new IllegalArgumentException("Parameter operationId is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.client.endpoint()); + return service.getOperationStatus(operationId, this.client.acceptLanguage(), parameterizedHost, this.client.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getOperationStatusDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getOperationStatusDelegate(Response response) throws APIErrorException, IOException, IllegalArgumentException { + return this.client.restClient().responseBuilderFactory().newInstance(this.client.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(APIErrorException.class) + .build(response); + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/package-info.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/package-info.java index 5890cb1a5db8..34c335c4ef0d 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/package-info.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/implementation/package-info.java @@ -5,7 +5,7 @@ // Code generated by Microsoft (R) AutoRest Code Generator. /** - * This package contains the implementation classes for FaceAPI. + * This package contains the implementation classes for FaceClient. * An API for face detection, verification, and identification. */ package com.microsoft.azure.cognitiveservices.vision.faceapi.implementation; diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Accessory.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Accessory.java index db1dd7ec6818..f09314a9ce90 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Accessory.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Accessory.java @@ -28,7 +28,7 @@ public class Accessory { private double confidence; /** - * Get the type value. + * Get type of an accessory. Possible values include: 'headWear', 'glasses', 'mask'. * * @return the type value */ @@ -37,7 +37,7 @@ public AccessoryType type() { } /** - * Set the type value. + * Set type of an accessory. Possible values include: 'headWear', 'glasses', 'mask'. * * @param type the type value to set * @return the Accessory object itself. @@ -48,7 +48,7 @@ public Accessory withType(AccessoryType type) { } /** - * Get the confidence value. + * Get confidence level of an accessory. * * @return the confidence value */ @@ -57,7 +57,7 @@ public double confidence() { } /** - * Set the confidence value. + * Set confidence level of an accessory. * * @param confidence the confidence value to set * @return the Accessory object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ApplySnapshotRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ApplySnapshotRequest.java new file mode 100644 index 000000000000..268e1111109c --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ApplySnapshotRequest.java @@ -0,0 +1,73 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Request body for applying snapshot operation. + */ +public class ApplySnapshotRequest { + /** + * User specified target object id to be created from the snapshot. + */ + @JsonProperty(value = "objectId", required = true) + private String objectId; + + /** + * Snapshot applying mode. Currently only CreateNew is supported, which + * means the apply operation will fail if target subscription already + * contains an object of same type and using the same objectId. Users can + * specify the "objectId" in request body to avoid such conflicts. Possible + * values include: 'CreateNew'. + */ + @JsonProperty(value = "mode") + private SnapshotApplyMode mode; + + /** + * Get user specified target object id to be created from the snapshot. + * + * @return the objectId value + */ + public String objectId() { + return this.objectId; + } + + /** + * Set user specified target object id to be created from the snapshot. + * + * @param objectId the objectId value to set + * @return the ApplySnapshotRequest object itself. + */ + public ApplySnapshotRequest withObjectId(String objectId) { + this.objectId = objectId; + return this; + } + + /** + * Get snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew'. + * + * @return the mode value + */ + public SnapshotApplyMode mode() { + return this.mode; + } + + /** + * Set snapshot applying mode. Currently only CreateNew is supported, which means the apply operation will fail if target subscription already contains an object of same type and using the same objectId. Users can specify the "objectId" in request body to avoid such conflicts. Possible values include: 'CreateNew'. + * + * @param mode the mode value to set + * @return the ApplySnapshotRequest object itself. + */ + public ApplySnapshotRequest withMode(SnapshotApplyMode mode) { + this.mode = mode; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Blur.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Blur.java index 6600c2679ec3..24fa48618f9b 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Blur.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Blur.java @@ -28,7 +28,7 @@ public class Blur { private double value; /** - * Get the blurLevel value. + * Get an enum value indicating level of blurriness. Possible values include: 'Low', 'Medium', 'High'. * * @return the blurLevel value */ @@ -37,7 +37,7 @@ public BlurLevel blurLevel() { } /** - * Set the blurLevel value. + * Set an enum value indicating level of blurriness. Possible values include: 'Low', 'Medium', 'High'. * * @param blurLevel the blurLevel value to set * @return the Blur object itself. @@ -48,7 +48,7 @@ public Blur withBlurLevel(BlurLevel blurLevel) { } /** - * Get the value value. + * Get a number indicating level of blurriness ranging from 0 to 1. * * @return the value value */ @@ -57,7 +57,7 @@ public double value() { } /** - * Set the value value. + * Set a number indicating level of blurriness ranging from 0 to 1. * * @param value the value value to set * @return the Blur object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Coordinate.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Coordinate.java index 6490f235c048..9615465ef312 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Coordinate.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Coordinate.java @@ -27,7 +27,7 @@ public class Coordinate { private double y; /** - * Get the x value. + * Get the horizontal component, in pixels. * * @return the x value */ @@ -36,7 +36,7 @@ public double x() { } /** - * Set the x value. + * Set the horizontal component, in pixels. * * @param x the x value to set * @return the Coordinate object itself. @@ -47,7 +47,7 @@ public Coordinate withX(double x) { } /** - * Get the y value. + * Get the vertical component, in pixels. * * @return the y value */ @@ -56,7 +56,7 @@ public double y() { } /** - * Set the y value. + * Set the vertical component, in pixels. * * @param y the y value to set * @return the Coordinate object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/DetectedFace.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/DetectedFace.java index ef7ca60b1330..3409e91cf06d 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/DetectedFace.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/DetectedFace.java @@ -21,6 +21,12 @@ public class DetectedFace { @JsonProperty(value = "faceId") private UUID faceId; + /** + * Possible values include: 'recognition_01', 'recognition_02'. + */ + @JsonProperty(value = "recognitionModel") + private RecognitionModel recognitionModel; + /** * The faceRectangle property. */ @@ -59,6 +65,26 @@ public DetectedFace withFaceId(UUID faceId) { return this; } + /** + * Get possible values include: 'recognition_01', 'recognition_02'. + * + * @return the recognitionModel value + */ + public RecognitionModel recognitionModel() { + return this.recognitionModel; + } + + /** + * Set possible values include: 'recognition_01', 'recognition_02'. + * + * @param recognitionModel the recognitionModel value to set + * @return the DetectedFace object itself. + */ + public DetectedFace withRecognitionModel(RecognitionModel recognitionModel) { + this.recognitionModel = recognitionModel; + return this; + } + /** * Get the faceRectangle value. * diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Exposure.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Exposure.java index 15ddf53fc2ae..822f1888ace8 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Exposure.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Exposure.java @@ -30,7 +30,7 @@ public class Exposure { private double value; /** - * Get the exposureLevel value. + * Get an enum value indicating level of exposure. Possible values include: 'UnderExposure', 'GoodExposure', 'OverExposure'. * * @return the exposureLevel value */ @@ -39,7 +39,7 @@ public ExposureLevel exposureLevel() { } /** - * Set the exposureLevel value. + * Set an enum value indicating level of exposure. Possible values include: 'UnderExposure', 'GoodExposure', 'OverExposure'. * * @param exposureLevel the exposureLevel value to set * @return the Exposure object itself. @@ -50,7 +50,7 @@ public Exposure withExposureLevel(ExposureLevel exposureLevel) { } /** - * Get the value value. + * Get a number indicating level of exposure level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. * * @return the value value */ @@ -59,7 +59,7 @@ public double value() { } /** - * Set the value value. + * Set a number indicating level of exposure level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. * * @param value the value value to set * @return the Exposure object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceAttributes.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceAttributes.java index a0e8bd76f3a0..71ac11b38cfe 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceAttributes.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceAttributes.java @@ -22,8 +22,7 @@ public class FaceAttributes { private Double age; /** - * Possible gender of the face. Possible values include: 'male', 'female', - * 'genderless'. + * Possible gender of the face. Possible values include: 'male', 'female'. */ @JsonProperty(value = "gender") private Gender gender; @@ -103,7 +102,7 @@ public class FaceAttributes { private Noise noise; /** - * Get the age value. + * Get age in years. * * @return the age value */ @@ -112,7 +111,7 @@ public Double age() { } /** - * Set the age value. + * Set age in years. * * @param age the age value to set * @return the FaceAttributes object itself. @@ -123,7 +122,7 @@ public FaceAttributes withAge(Double age) { } /** - * Get the gender value. + * Get possible gender of the face. Possible values include: 'male', 'female'. * * @return the gender value */ @@ -132,7 +131,7 @@ public Gender gender() { } /** - * Set the gender value. + * Set possible gender of the face. Possible values include: 'male', 'female'. * * @param gender the gender value to set * @return the FaceAttributes object itself. @@ -143,7 +142,7 @@ public FaceAttributes withGender(Gender gender) { } /** - * Get the smile value. + * Get smile intensity, a number between [0,1]. * * @return the smile value */ @@ -152,7 +151,7 @@ public Double smile() { } /** - * Set the smile value. + * Set smile intensity, a number between [0,1]. * * @param smile the smile value to set * @return the FaceAttributes object itself. @@ -163,7 +162,7 @@ public FaceAttributes withSmile(Double smile) { } /** - * Get the facialHair value. + * Get properties describing facial hair attributes. * * @return the facialHair value */ @@ -172,7 +171,7 @@ public FacialHair facialHair() { } /** - * Set the facialHair value. + * Set properties describing facial hair attributes. * * @param facialHair the facialHair value to set * @return the FaceAttributes object itself. @@ -183,7 +182,7 @@ public FaceAttributes withFacialHair(FacialHair facialHair) { } /** - * Get the glasses value. + * Get glasses type if any of the face. Possible values include: 'noGlasses', 'readingGlasses', 'sunglasses', 'swimmingGoggles'. * * @return the glasses value */ @@ -192,7 +191,7 @@ public GlassesType glasses() { } /** - * Set the glasses value. + * Set glasses type if any of the face. Possible values include: 'noGlasses', 'readingGlasses', 'sunglasses', 'swimmingGoggles'. * * @param glasses the glasses value to set * @return the FaceAttributes object itself. @@ -203,7 +202,7 @@ public FaceAttributes withGlasses(GlassesType glasses) { } /** - * Get the headPose value. + * Get properties indicating head pose of the face. * * @return the headPose value */ @@ -212,7 +211,7 @@ public HeadPose headPose() { } /** - * Set the headPose value. + * Set properties indicating head pose of the face. * * @param headPose the headPose value to set * @return the FaceAttributes object itself. @@ -223,7 +222,7 @@ public FaceAttributes withHeadPose(HeadPose headPose) { } /** - * Get the emotion value. + * Get properties describing facial emotion in form of confidence ranging from 0 to 1. * * @return the emotion value */ @@ -232,7 +231,7 @@ public Emotion emotion() { } /** - * Set the emotion value. + * Set properties describing facial emotion in form of confidence ranging from 0 to 1. * * @param emotion the emotion value to set * @return the FaceAttributes object itself. @@ -243,7 +242,7 @@ public FaceAttributes withEmotion(Emotion emotion) { } /** - * Get the hair value. + * Get properties describing hair attributes. * * @return the hair value */ @@ -252,7 +251,7 @@ public Hair hair() { } /** - * Set the hair value. + * Set properties describing hair attributes. * * @param hair the hair value to set * @return the FaceAttributes object itself. @@ -263,7 +262,7 @@ public FaceAttributes withHair(Hair hair) { } /** - * Get the makeup value. + * Get properties describing present makeups on a given face. * * @return the makeup value */ @@ -272,7 +271,7 @@ public Makeup makeup() { } /** - * Set the makeup value. + * Set properties describing present makeups on a given face. * * @param makeup the makeup value to set * @return the FaceAttributes object itself. @@ -283,7 +282,7 @@ public FaceAttributes withMakeup(Makeup makeup) { } /** - * Get the occlusion value. + * Get properties describing occlusions on a given face. * * @return the occlusion value */ @@ -292,7 +291,7 @@ public Occlusion occlusion() { } /** - * Set the occlusion value. + * Set properties describing occlusions on a given face. * * @param occlusion the occlusion value to set * @return the FaceAttributes object itself. @@ -303,7 +302,7 @@ public FaceAttributes withOcclusion(Occlusion occlusion) { } /** - * Get the accessories value. + * Get properties describing any accessories on a given face. * * @return the accessories value */ @@ -312,7 +311,7 @@ public List accessories() { } /** - * Set the accessories value. + * Set properties describing any accessories on a given face. * * @param accessories the accessories value to set * @return the FaceAttributes object itself. @@ -323,7 +322,7 @@ public FaceAttributes withAccessories(List accessories) { } /** - * Get the blur value. + * Get properties describing any presence of blur within the image. * * @return the blur value */ @@ -332,7 +331,7 @@ public Blur blur() { } /** - * Set the blur value. + * Set properties describing any presence of blur within the image. * * @param blur the blur value to set * @return the FaceAttributes object itself. @@ -343,7 +342,7 @@ public FaceAttributes withBlur(Blur blur) { } /** - * Get the exposure value. + * Get properties describing exposure level of the image. * * @return the exposure value */ @@ -352,7 +351,7 @@ public Exposure exposure() { } /** - * Set the exposure value. + * Set properties describing exposure level of the image. * * @param exposure the exposure value to set * @return the FaceAttributes object itself. @@ -363,7 +362,7 @@ public FaceAttributes withExposure(Exposure exposure) { } /** - * Get the noise value. + * Get properties describing noise level of the image. * * @return the noise value */ @@ -372,7 +371,7 @@ public Noise noise() { } /** - * Set the noise value. + * Set properties describing noise level of the image. * * @param noise the noise value to set * @return the FaceAttributes object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceList.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceList.java index d31c2e886266..f62425e8cfdd 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceList.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceList.java @@ -14,7 +14,7 @@ /** * Face list object. */ -public class FaceList extends NameAndUserDataContract { +public class FaceList extends MetaDataContract { /** * FaceListId of the target face list. */ @@ -28,7 +28,7 @@ public class FaceList extends NameAndUserDataContract { private List persistedFaces; /** - * Get the faceListId value. + * Get faceListId of the target face list. * * @return the faceListId value */ @@ -37,7 +37,7 @@ public String faceListId() { } /** - * Set the faceListId value. + * Set faceListId of the target face list. * * @param faceListId the faceListId value to set * @return the FaceList object itself. @@ -48,7 +48,7 @@ public FaceList withFaceListId(String faceListId) { } /** - * Get the persistedFaces value. + * Get persisted faces within the face list. * * @return the persistedFaces value */ @@ -57,7 +57,7 @@ public List persistedFaces() { } /** - * Set the persistedFaces value. + * Set persisted faces within the face list. * * @param persistedFaces the persistedFaces value to set * @return the FaceList object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceRectangle.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceRectangle.java index a3c64c9d73c7..e56a9e633bbe 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceRectangle.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FaceRectangle.java @@ -41,7 +41,7 @@ public class FaceRectangle { private int top; /** - * Get the width value. + * Get the width of the rectangle, in pixels. * * @return the width value */ @@ -50,7 +50,7 @@ public int width() { } /** - * Set the width value. + * Set the width of the rectangle, in pixels. * * @param width the width value to set * @return the FaceRectangle object itself. @@ -61,7 +61,7 @@ public FaceRectangle withWidth(int width) { } /** - * Get the height value. + * Get the height of the rectangle, in pixels. * * @return the height value */ @@ -70,7 +70,7 @@ public int height() { } /** - * Set the height value. + * Set the height of the rectangle, in pixels. * * @param height the height value to set * @return the FaceRectangle object itself. @@ -81,7 +81,7 @@ public FaceRectangle withHeight(int height) { } /** - * Get the left value. + * Get the distance from the left edge if the image to the left edge of the rectangle, in pixels. * * @return the left value */ @@ -90,7 +90,7 @@ public int left() { } /** - * Set the left value. + * Set the distance from the left edge if the image to the left edge of the rectangle, in pixels. * * @param left the left value to set * @return the FaceRectangle object itself. @@ -101,7 +101,7 @@ public FaceRectangle withLeft(int left) { } /** - * Get the top value. + * Get the distance from the top edge if the image to the top edge of the rectangle, in pixels. * * @return the top value */ @@ -110,7 +110,7 @@ public int top() { } /** - * Set the top value. + * Set the distance from the top edge if the image to the top edge of the rectangle, in pixels. * * @param top the top value to set * @return the FaceRectangle object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FindSimilarRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FindSimilarRequest.java index 109bfbb56460..4b210b15164a 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FindSimilarRequest.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/FindSimilarRequest.java @@ -27,15 +27,27 @@ public class FindSimilarRequest { /** * An existing user-specified unique candidate face list, created in Face * List - Create a Face List. Face list contains a set of persistedFaceIds - * which are persisted and will never expire. Parameter faceListId and - * faceIds should not be provided at the same time. + * which are persisted and will never expire. Parameter faceListId, + * largeFaceListId and faceIds should not be provided at the same time. */ @JsonProperty(value = "faceListId") private String faceListId; + /** + * An existing user-specified unique candidate large face list, created in + * LargeFaceList - Create. Large face list contains a set of + * persistedFaceIds which are persisted and will never expire. Parameter + * faceListId, largeFaceListId and faceIds should not be provided at the + * same time. + */ + @JsonProperty(value = "largeFaceListId") + private String largeFaceListId; + /** * An array of candidate faceIds. All of them are created by Face - Detect - * and the faceIds will expire 24 hours after the detection call. + * and the faceIds will expire 24 hours after the detection call. The + * number of faceIds is limited to 1000. Parameter faceListId, + * largeFaceListId and faceIds should not be provided at the same time. */ @JsonProperty(value = "faceIds") private List faceIds; @@ -54,7 +66,7 @@ public class FindSimilarRequest { private FindSimilarMatchMode mode; /** - * Get the faceId value. + * Get faceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call. * * @return the faceId value */ @@ -63,7 +75,7 @@ public UUID faceId() { } /** - * Set the faceId value. + * Set faceId of the query face. User needs to call Face - Detect first to get a valid faceId. Note that this faceId is not persisted and will expire 24 hours after the detection call. * * @param faceId the faceId value to set * @return the FindSimilarRequest object itself. @@ -74,7 +86,7 @@ public FindSimilarRequest withFaceId(UUID faceId) { } /** - * Get the faceListId value. + * Get an existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. * * @return the faceListId value */ @@ -83,7 +95,7 @@ public String faceListId() { } /** - * Set the faceListId value. + * Set an existing user-specified unique candidate face list, created in Face List - Create a Face List. Face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. * * @param faceListId the faceListId value to set * @return the FindSimilarRequest object itself. @@ -94,7 +106,27 @@ public FindSimilarRequest withFaceListId(String faceListId) { } /** - * Get the faceIds value. + * Get an existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * + * @return the largeFaceListId value + */ + public String largeFaceListId() { + return this.largeFaceListId; + } + + /** + * Set an existing user-specified unique candidate large face list, created in LargeFaceList - Create. Large face list contains a set of persistedFaceIds which are persisted and will never expire. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. + * + * @param largeFaceListId the largeFaceListId value to set + * @return the FindSimilarRequest object itself. + */ + public FindSimilarRequest withLargeFaceListId(String largeFaceListId) { + this.largeFaceListId = largeFaceListId; + return this; + } + + /** + * Get an array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. * * @return the faceIds value */ @@ -103,7 +135,7 @@ public List faceIds() { } /** - * Set the faceIds value. + * Set an array of candidate faceIds. All of them are created by Face - Detect and the faceIds will expire 24 hours after the detection call. The number of faceIds is limited to 1000. Parameter faceListId, largeFaceListId and faceIds should not be provided at the same time. * * @param faceIds the faceIds value to set * @return the FindSimilarRequest object itself. @@ -114,7 +146,7 @@ public FindSimilarRequest withFaceIds(List faceIds) { } /** - * Get the maxNumOfCandidatesReturned value. + * Get the number of top similar faces returned. The valid range is [1, 1000]. * * @return the maxNumOfCandidatesReturned value */ @@ -123,7 +155,7 @@ public Integer maxNumOfCandidatesReturned() { } /** - * Set the maxNumOfCandidatesReturned value. + * Set the number of top similar faces returned. The valid range is [1, 1000]. * * @param maxNumOfCandidatesReturned the maxNumOfCandidatesReturned value to set * @return the FindSimilarRequest object itself. @@ -134,7 +166,7 @@ public FindSimilarRequest withMaxNumOfCandidatesReturned(Integer maxNumOfCandida } /** - * Get the mode value. + * Get similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace'. * * @return the mode value */ @@ -143,7 +175,7 @@ public FindSimilarMatchMode mode() { } /** - * Set the mode value. + * Set similar face searching mode. It can be "matchPerson" or "matchFace". Possible values include: 'matchPerson', 'matchFace'. * * @param mode the mode value to set * @return the FindSimilarRequest object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Gender.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Gender.java index 811b4e5ebc35..27effc4b2319 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Gender.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Gender.java @@ -19,10 +19,7 @@ public enum Gender { MALE("male"), /** Enum value female. */ - FEMALE("female"), - - /** Enum value genderless. */ - GENDERLESS("genderless"); + FEMALE("female"); /** The actual serialized value for a Gender instance. */ private String value; diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupRequest.java index e2c8c8dcf281..c44ee8495a56 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupRequest.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupRequest.java @@ -24,7 +24,7 @@ public class GroupRequest { private List faceIds; /** - * Get the faceIds value. + * Get array of candidate faceId created by Face - Detect. The maximum is 1000 faces. * * @return the faceIds value */ @@ -33,7 +33,7 @@ public List faceIds() { } /** - * Set the faceIds value. + * Set array of candidate faceId created by Face - Detect. The maximum is 1000 faces. * * @param faceIds the faceIds value to set * @return the GroupRequest object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupResult.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupResult.java index 86e0fdbfd448..c2440f2b8c52 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupResult.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/GroupResult.java @@ -31,7 +31,7 @@ public class GroupResult { private List messyGroup; /** - * Get the groups value. + * Get a partition of the original faces based on face similarity. Groups are ranked by number of faces. * * @return the groups value */ @@ -40,7 +40,7 @@ public List> groups() { } /** - * Set the groups value. + * Set a partition of the original faces based on face similarity. Groups are ranked by number of faces. * * @param groups the groups value to set * @return the GroupResult object itself. @@ -51,7 +51,7 @@ public GroupResult withGroups(List> groups) { } /** - * Get the messyGroup value. + * Get face ids array of faces that cannot find any similar faces from original faces. * * @return the messyGroup value */ @@ -60,7 +60,7 @@ public List messyGroup() { } /** - * Set the messyGroup value. + * Set face ids array of faces that cannot find any similar faces from original faces. * * @param messyGroup the messyGroup value to set * @return the GroupResult object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Hair.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Hair.java index 074ae217a0c4..49abb7342db8 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Hair.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Hair.java @@ -35,7 +35,7 @@ public class Hair { private List hairColor; /** - * Get the bald value. + * Get a number describing confidence level of whether the person is bald. * * @return the bald value */ @@ -44,7 +44,7 @@ public double bald() { } /** - * Set the bald value. + * Set a number describing confidence level of whether the person is bald. * * @param bald the bald value to set * @return the Hair object itself. @@ -55,7 +55,7 @@ public Hair withBald(double bald) { } /** - * Get the invisible value. + * Get a boolean value describing whether the hair is visible in the image. * * @return the invisible value */ @@ -64,7 +64,7 @@ public boolean invisible() { } /** - * Set the invisible value. + * Set a boolean value describing whether the hair is visible in the image. * * @param invisible the invisible value to set * @return the Hair object itself. @@ -75,7 +75,7 @@ public Hair withInvisible(boolean invisible) { } /** - * Get the hairColor value. + * Get an array of candidate colors and confidence level in the presence of each. * * @return the hairColor value */ @@ -84,7 +84,7 @@ public List hairColor() { } /** - * Set the hairColor value. + * Set an array of candidate colors and confidence level in the presence of each. * * @param hairColor the hairColor value to set * @return the Hair object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/HairColor.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/HairColor.java index 923a82973dbe..9e65e237ce90 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/HairColor.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/HairColor.java @@ -28,7 +28,7 @@ public class HairColor { private double confidence; /** - * Get the color value. + * Get name of the hair color. Possible values include: 'unknown', 'white', 'gray', 'blond', 'brown', 'red', 'black', 'other'. * * @return the color value */ @@ -37,7 +37,7 @@ public HairColorType color() { } /** - * Set the color value. + * Set name of the hair color. Possible values include: 'unknown', 'white', 'gray', 'blond', 'brown', 'red', 'black', 'other'. * * @param color the color value to set * @return the HairColor object itself. @@ -48,7 +48,7 @@ public HairColor withColor(HairColorType color) { } /** - * Get the confidence value. + * Get confidence level of the color. * * @return the confidence value */ @@ -57,7 +57,7 @@ public double confidence() { } /** - * Set the confidence value. + * Set confidence level of the color. * * @param confidence the confidence value to set * @return the HairColor object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyCandidate.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyCandidate.java index 3f2f00a03d79..b0e9218869f1 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyCandidate.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyCandidate.java @@ -30,7 +30,7 @@ public class IdentifyCandidate { private double confidence; /** - * Get the personId value. + * Get id of candidate. * * @return the personId value */ @@ -39,7 +39,7 @@ public UUID personId() { } /** - * Set the personId value. + * Set id of candidate. * * @param personId the personId value to set * @return the IdentifyCandidate object itself. @@ -50,7 +50,7 @@ public IdentifyCandidate withPersonId(UUID personId) { } /** - * Get the confidence value. + * Get confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). * * @return the confidence value */ @@ -59,7 +59,7 @@ public double confidence() { } /** - * Set the confidence value. + * Set confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). * * @param confidence the confidence value to set * @return the IdentifyCandidate object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyRequest.java index de63a2dd4596..ea62ca005dc7 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyRequest.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyRequest.java @@ -16,13 +16,6 @@ * Request body for identify face operation. */ public class IdentifyRequest { - /** - * PersonGroupId of the target person group, created by - * PersonGroups.Create. - */ - @JsonProperty(value = "personGroupId", required = true) - private String personGroupId; - /** * Array of query faces faceIds, created by the Face - Detect. Each of the * faces are identified independently. The valid number of faceIds is @@ -31,6 +24,22 @@ public class IdentifyRequest { @JsonProperty(value = "faceIds", required = true) private List faceIds; + /** + * PersonGroupId of the target person group, created by PersonGroup - + * Create. Parameter personGroupId and largePersonGroupId should not be + * provided at the same time. + */ + @JsonProperty(value = "personGroupId") + private String personGroupId; + + /** + * LargePersonGroupId of the target large person group, created by + * LargePersonGroup - Create. Parameter personGroupId and + * largePersonGroupId should not be provided at the same time. + */ + @JsonProperty(value = "largePersonGroupId") + private String largePersonGroupId; + /** * The range of maxNumOfCandidatesReturned is between 1 and 5 (default is * 1). @@ -47,7 +56,27 @@ public class IdentifyRequest { private Double confidenceThreshold; /** - * Get the personGroupId value. + * Get array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * + * @return the faceIds value + */ + public List faceIds() { + return this.faceIds; + } + + /** + * Set array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. + * + * @param faceIds the faceIds value to set + * @return the IdentifyRequest object itself. + */ + public IdentifyRequest withFaceIds(List faceIds) { + this.faceIds = faceIds; + return this; + } + + /** + * Get personGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * * @return the personGroupId value */ @@ -56,7 +85,7 @@ public String personGroupId() { } /** - * Set the personGroupId value. + * Set personGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * * @param personGroupId the personGroupId value to set * @return the IdentifyRequest object itself. @@ -67,27 +96,27 @@ public IdentifyRequest withPersonGroupId(String personGroupId) { } /** - * Get the faceIds value. + * Get largePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * - * @return the faceIds value + * @return the largePersonGroupId value */ - public List faceIds() { - return this.faceIds; + public String largePersonGroupId() { + return this.largePersonGroupId; } /** - * Set the faceIds value. + * Set largePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * - * @param faceIds the faceIds value to set + * @param largePersonGroupId the largePersonGroupId value to set * @return the IdentifyRequest object itself. */ - public IdentifyRequest withFaceIds(List faceIds) { - this.faceIds = faceIds; + public IdentifyRequest withLargePersonGroupId(String largePersonGroupId) { + this.largePersonGroupId = largePersonGroupId; return this; } /** - * Get the maxNumOfCandidatesReturned value. + * Get the range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). * * @return the maxNumOfCandidatesReturned value */ @@ -96,7 +125,7 @@ public Integer maxNumOfCandidatesReturned() { } /** - * Set the maxNumOfCandidatesReturned value. + * Set the range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1). * * @param maxNumOfCandidatesReturned the maxNumOfCandidatesReturned value to set * @return the IdentifyRequest object itself. @@ -107,7 +136,7 @@ public IdentifyRequest withMaxNumOfCandidatesReturned(Integer maxNumOfCandidates } /** - * Get the confidenceThreshold value. + * Get confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). * * @return the confidenceThreshold value */ @@ -116,7 +145,7 @@ public Double confidenceThreshold() { } /** - * Set the confidenceThreshold value. + * Set confidence threshold of identification, used to judge whether one face belong to one person. The range of confidenceThreshold is [0, 1] (default specified by algorithm). * * @param confidenceThreshold the confidenceThreshold value to set * @return the IdentifyRequest object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyResult.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyResult.java index 282a35ae6c4d..554bab530306 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyResult.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/IdentifyResult.java @@ -31,7 +31,7 @@ public class IdentifyResult { private List candidates; /** - * Get the faceId value. + * Get faceId of the query face. * * @return the faceId value */ @@ -40,7 +40,7 @@ public UUID faceId() { } /** - * Set the faceId value. + * Set faceId of the query face. * * @param faceId the faceId value to set * @return the IdentifyResult object itself. @@ -51,7 +51,7 @@ public IdentifyResult withFaceId(UUID faceId) { } /** - * Get the candidates value. + * Get identified person candidates for that face (ranked by confidence). Array size should be no larger than input maxNumOfCandidatesReturned. If no person is identified, will return an empty array. * * @return the candidates value */ @@ -60,7 +60,7 @@ public List candidates() { } /** - * Set the candidates value. + * Set identified person candidates for that face (ranked by confidence). Array size should be no larger than input maxNumOfCandidatesReturned. If no person is identified, will return an empty array. * * @param candidates the candidates value to set * @return the IdentifyResult object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ImageUrl.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ImageUrl.java index 3372efa615a0..b5a41095a324 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ImageUrl.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/ImageUrl.java @@ -21,7 +21,7 @@ public class ImageUrl { private String url; /** - * Get the url value. + * Get publicly reachable URL of an image. * * @return the url value */ @@ -30,7 +30,7 @@ public String url() { } /** - * Set the url value. + * Set publicly reachable URL of an image. * * @param url the url value to set * @return the ImageUrl object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargeFaceList.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargeFaceList.java new file mode 100644 index 000000000000..9dc77c678722 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargeFaceList.java @@ -0,0 +1,43 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Large face list object. + */ +public class LargeFaceList extends MetaDataContract { + /** + * LargeFaceListId of the target large face list. + */ + @JsonProperty(value = "largeFaceListId", required = true) + private String largeFaceListId; + + /** + * Get largeFaceListId of the target large face list. + * + * @return the largeFaceListId value + */ + public String largeFaceListId() { + return this.largeFaceListId; + } + + /** + * Set largeFaceListId of the target large face list. + * + * @param largeFaceListId the largeFaceListId value to set + * @return the LargeFaceList object itself. + */ + public LargeFaceList withLargeFaceListId(String largeFaceListId) { + this.largeFaceListId = largeFaceListId; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargePersonGroup.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargePersonGroup.java new file mode 100644 index 000000000000..b26b7eef0e94 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/LargePersonGroup.java @@ -0,0 +1,43 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Large person group object. + */ +public class LargePersonGroup extends MetaDataContract { + /** + * LargePersonGroupId of the target large person groups. + */ + @JsonProperty(value = "largePersonGroupId", required = true) + private String largePersonGroupId; + + /** + * Get largePersonGroupId of the target large person groups. + * + * @return the largePersonGroupId value + */ + public String largePersonGroupId() { + return this.largePersonGroupId; + } + + /** + * Set largePersonGroupId of the target large person groups. + * + * @param largePersonGroupId the largePersonGroupId value to set + * @return the LargePersonGroup object itself. + */ + public LargePersonGroup withLargePersonGroupId(String largePersonGroupId) { + this.largePersonGroupId = largePersonGroupId; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Makeup.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Makeup.java index d0ae91e1294a..0f9923c6e30d 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Makeup.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Makeup.java @@ -27,7 +27,7 @@ public class Makeup { private boolean lipMakeup; /** - * Get the eyeMakeup value. + * Get a boolean value describing whether eye makeup is present on a face. * * @return the eyeMakeup value */ @@ -36,7 +36,7 @@ public boolean eyeMakeup() { } /** - * Set the eyeMakeup value. + * Set a boolean value describing whether eye makeup is present on a face. * * @param eyeMakeup the eyeMakeup value to set * @return the Makeup object itself. @@ -47,7 +47,7 @@ public Makeup withEyeMakeup(boolean eyeMakeup) { } /** - * Get the lipMakeup value. + * Get a boolean value describing whether lip makeup is present on a face. * * @return the lipMakeup value */ @@ -56,7 +56,7 @@ public boolean lipMakeup() { } /** - * Set the lipMakeup value. + * Set a boolean value describing whether lip makeup is present on a face. * * @param lipMakeup the lipMakeup value to set * @return the Makeup object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/MetaDataContract.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/MetaDataContract.java new file mode 100644 index 000000000000..93d3f395e6c8 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/MetaDataContract.java @@ -0,0 +1,44 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * A combination of user defined name and user specified data and recognition + * model name for largePersonGroup/personGroup, and largeFaceList/faceList. + */ +public class MetaDataContract extends NameAndUserDataContract { + /** + * Possible values include: 'recognition_01', 'recognition_02'. + */ + @JsonProperty(value = "recognitionModel") + private RecognitionModel recognitionModel; + + /** + * Get possible values include: 'recognition_01', 'recognition_02'. + * + * @return the recognitionModel value + */ + public RecognitionModel recognitionModel() { + return this.recognitionModel; + } + + /** + * Set possible values include: 'recognition_01', 'recognition_02'. + * + * @param recognitionModel the recognitionModel value to set + * @return the MetaDataContract object itself. + */ + public MetaDataContract withRecognitionModel(RecognitionModel recognitionModel) { + this.recognitionModel = recognitionModel; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/NameAndUserDataContract.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/NameAndUserDataContract.java index f91ac6b65e98..f6c31c6e1f35 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/NameAndUserDataContract.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/NameAndUserDataContract.java @@ -12,7 +12,7 @@ /** * A combination of user defined name and user specified data for the person, - * personGroup, and faceList. + * largePersonGroup/personGroup, and largeFaceList/faceList. */ public class NameAndUserDataContract { /** @@ -28,7 +28,7 @@ public class NameAndUserDataContract { private String userData; /** - * Get the name value. + * Get user defined name, maximum length is 128. * * @return the name value */ @@ -37,7 +37,7 @@ public String name() { } /** - * Set the name value. + * Set user defined name, maximum length is 128. * * @param name the name value to set * @return the NameAndUserDataContract object itself. @@ -48,7 +48,7 @@ public NameAndUserDataContract withName(String name) { } /** - * Get the userData value. + * Get user specified data. Length should not exceed 16KB. * * @return the userData value */ @@ -57,7 +57,7 @@ public String userData() { } /** - * Set the userData value. + * Set user specified data. Length should not exceed 16KB. * * @param userData the userData value to set * @return the NameAndUserDataContract object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Noise.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Noise.java index 6d347f644dc4..946f9e70f347 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Noise.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Noise.java @@ -31,7 +31,7 @@ public class Noise { private double value; /** - * Get the noiseLevel value. + * Get an enum value indicating level of noise. Possible values include: 'Low', 'Medium', 'High'. * * @return the noiseLevel value */ @@ -40,7 +40,7 @@ public NoiseLevel noiseLevel() { } /** - * Set the noiseLevel value. + * Set an enum value indicating level of noise. Possible values include: 'Low', 'Medium', 'High'. * * @param noiseLevel the noiseLevel value to set * @return the Noise object itself. @@ -51,7 +51,7 @@ public Noise withNoiseLevel(NoiseLevel noiseLevel) { } /** - * Get the value value. + * Get a number indicating level of noise level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise level. [0.7, 1] is high noise level. * * @return the value value */ @@ -60,7 +60,7 @@ public double value() { } /** - * Set the value value. + * Set a number indicating level of noise level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise level. [0.7, 1] is high noise level. * * @param value the value value to set * @return the Noise object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Occlusion.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Occlusion.java index c7fd8df4522b..7a75a5659f5d 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Occlusion.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Occlusion.java @@ -33,7 +33,7 @@ public class Occlusion { private boolean mouthOccluded; /** - * Get the foreheadOccluded value. + * Get a boolean value indicating whether forehead is occluded. * * @return the foreheadOccluded value */ @@ -42,7 +42,7 @@ public boolean foreheadOccluded() { } /** - * Set the foreheadOccluded value. + * Set a boolean value indicating whether forehead is occluded. * * @param foreheadOccluded the foreheadOccluded value to set * @return the Occlusion object itself. @@ -53,7 +53,7 @@ public Occlusion withForeheadOccluded(boolean foreheadOccluded) { } /** - * Get the eyeOccluded value. + * Get a boolean value indicating whether eyes are occluded. * * @return the eyeOccluded value */ @@ -62,7 +62,7 @@ public boolean eyeOccluded() { } /** - * Set the eyeOccluded value. + * Set a boolean value indicating whether eyes are occluded. * * @param eyeOccluded the eyeOccluded value to set * @return the Occlusion object itself. @@ -73,7 +73,7 @@ public Occlusion withEyeOccluded(boolean eyeOccluded) { } /** - * Get the mouthOccluded value. + * Get a boolean value indicating whether the mouth is occluded. * * @return the mouthOccluded value */ @@ -82,7 +82,7 @@ public boolean mouthOccluded() { } /** - * Set the mouthOccluded value. + * Set a boolean value indicating whether the mouth is occluded. * * @param mouthOccluded the mouthOccluded value to set * @return the Occlusion object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatus.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatus.java new file mode 100644 index 000000000000..c6a3c9cc0ab7 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatus.java @@ -0,0 +1,169 @@ +/** + * 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.models; + +import org.joda.time.DateTime; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Operation status object. Operation refers to the asynchronous backend task + * including taking a snapshot and applying a snapshot. + */ +public class OperationStatus { + /** + * Operation status: notstarted, running, succeeded, failed. If the + * operation is requested and waiting to perform, the status is notstarted. + * If the operation is ongoing in backend, the status is running. Status + * succeeded means the operation is completed successfully, specifically + * for snapshot taking operation, it illustrates the snapshot is well taken + * and ready to apply, and for snapshot applying operation, it presents the + * target object has finished creating by the snapshot and ready to be + * used. Status failed is often caused by editing the source object while + * taking the snapshot or editing the target object while applying the + * snapshot before completion, see the field "message" to check the failure + * reason. Possible values include: 'notstarted', 'running', 'succeeded', + * 'failed'. + */ + @JsonProperty(value = "status", required = true) + private OperationStatusType status; + + /** + * A combined UTC date and time string that describes the time when the + * operation (take or apply a snapshot) is requested. E.g. + * 2018-12-25T11:41:02.2331413Z. + */ + @JsonProperty(value = "createdTime", required = true) + private DateTime createdTime; + + /** + * A combined UTC date and time string that describes the last time the + * operation (take or apply a snapshot) is actively migrating data. The + * lastActionTime will keep increasing until the operation finishes. E.g. + * 2018-12-25T11:51:27.8705696Z. + */ + @JsonProperty(value = "lastActionTime") + private DateTime lastActionTime; + + /** + * When the operation succeeds successfully, for snapshot taking operation + * the snapshot id will be included in this field, and for snapshot + * applying operation, the path to get the target object will be returned + * in this field. + */ + @JsonProperty(value = "resourceLocation") + private String resourceLocation; + + /** + * Show failure message when operation fails (omitted when operation + * succeeds). + */ + @JsonProperty(value = "message") + private String message; + + /** + * Get operation status: notstarted, running, succeeded, failed. If the operation is requested and waiting to perform, the status is notstarted. If the operation is ongoing in backend, the status is running. Status succeeded means the operation is completed successfully, specifically for snapshot taking operation, it illustrates the snapshot is well taken and ready to apply, and for snapshot applying operation, it presents the target object has finished creating by the snapshot and ready to be used. Status failed is often caused by editing the source object while taking the snapshot or editing the target object while applying the snapshot before completion, see the field "message" to check the failure reason. Possible values include: 'notstarted', 'running', 'succeeded', 'failed'. + * + * @return the status value + */ + public OperationStatusType status() { + return this.status; + } + + /** + * Set operation status: notstarted, running, succeeded, failed. If the operation is requested and waiting to perform, the status is notstarted. If the operation is ongoing in backend, the status is running. Status succeeded means the operation is completed successfully, specifically for snapshot taking operation, it illustrates the snapshot is well taken and ready to apply, and for snapshot applying operation, it presents the target object has finished creating by the snapshot and ready to be used. Status failed is often caused by editing the source object while taking the snapshot or editing the target object while applying the snapshot before completion, see the field "message" to check the failure reason. Possible values include: 'notstarted', 'running', 'succeeded', 'failed'. + * + * @param status the status value to set + * @return the OperationStatus object itself. + */ + public OperationStatus withStatus(OperationStatusType status) { + this.status = status; + return this; + } + + /** + * Get a combined UTC date and time string that describes the time when the operation (take or apply a snapshot) is requested. E.g. 2018-12-25T11:41:02.2331413Z. + * + * @return the createdTime value + */ + public DateTime createdTime() { + return this.createdTime; + } + + /** + * Set a combined UTC date and time string that describes the time when the operation (take or apply a snapshot) is requested. E.g. 2018-12-25T11:41:02.2331413Z. + * + * @param createdTime the createdTime value to set + * @return the OperationStatus object itself. + */ + public OperationStatus withCreatedTime(DateTime createdTime) { + this.createdTime = createdTime; + return this; + } + + /** + * Get a combined UTC date and time string that describes the last time the operation (take or apply a snapshot) is actively migrating data. The lastActionTime will keep increasing until the operation finishes. E.g. 2018-12-25T11:51:27.8705696Z. + * + * @return the lastActionTime value + */ + public DateTime lastActionTime() { + return this.lastActionTime; + } + + /** + * Set a combined UTC date and time string that describes the last time the operation (take or apply a snapshot) is actively migrating data. The lastActionTime will keep increasing until the operation finishes. E.g. 2018-12-25T11:51:27.8705696Z. + * + * @param lastActionTime the lastActionTime value to set + * @return the OperationStatus object itself. + */ + public OperationStatus withLastActionTime(DateTime lastActionTime) { + this.lastActionTime = lastActionTime; + return this; + } + + /** + * Get when the operation succeeds successfully, for snapshot taking operation the snapshot id will be included in this field, and for snapshot applying operation, the path to get the target object will be returned in this field. + * + * @return the resourceLocation value + */ + public String resourceLocation() { + return this.resourceLocation; + } + + /** + * Set when the operation succeeds successfully, for snapshot taking operation the snapshot id will be included in this field, and for snapshot applying operation, the path to get the target object will be returned in this field. + * + * @param resourceLocation the resourceLocation value to set + * @return the OperationStatus object itself. + */ + public OperationStatus withResourceLocation(String resourceLocation) { + this.resourceLocation = resourceLocation; + return this; + } + + /** + * Get show failure message when operation fails (omitted when operation succeeds). + * + * @return the message value + */ + public String message() { + return this.message; + } + + /** + * Set show failure message when operation fails (omitted when operation succeeds). + * + * @param message the message value to set + * @return the OperationStatus object itself. + */ + public OperationStatus withMessage(String message) { + this.message = message; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatusType.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatusType.java new file mode 100644 index 000000000000..fc12ee253546 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/OperationStatusType.java @@ -0,0 +1,59 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonValue; + +/** + * Defines values for OperationStatusType. + */ +public enum OperationStatusType { + /** Enum value notstarted. */ + NOTSTARTED("notstarted"), + + /** Enum value running. */ + RUNNING("running"), + + /** Enum value succeeded. */ + SUCCEEDED("succeeded"), + + /** Enum value failed. */ + FAILED("failed"); + + /** The actual serialized value for a OperationStatusType instance. */ + private String value; + + OperationStatusType(String value) { + this.value = value; + } + + /** + * Parses a serialized value to a OperationStatusType instance. + * + * @param value the serialized value to parse. + * @return the parsed OperationStatusType object, or null if unable to parse. + */ + @JsonCreator + public static OperationStatusType fromString(String value) { + OperationStatusType[] items = OperationStatusType.values(); + for (OperationStatusType item : items) { + if (item.toString().equalsIgnoreCase(value)) { + return item; + } + } + return null; + } + + @JsonValue + @Override + public String toString() { + return this.value; + } +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersistedFace.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersistedFace.java index afff640ba4f3..d62e83ec4c37 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersistedFace.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersistedFace.java @@ -30,7 +30,7 @@ public class PersistedFace { private String userData; /** - * Get the persistedFaceId value. + * Get the persistedFaceId of the target face, which is persisted and will not expire. Different from faceId created by Face - Detect and will expire in 24 hours after the detection call. * * @return the persistedFaceId value */ @@ -39,7 +39,7 @@ public UUID persistedFaceId() { } /** - * Set the persistedFaceId value. + * Set the persistedFaceId of the target face, which is persisted and will not expire. Different from faceId created by Face - Detect and will expire in 24 hours after the detection call. * * @param persistedFaceId the persistedFaceId value to set * @return the PersistedFace object itself. @@ -50,7 +50,7 @@ public PersistedFace withPersistedFaceId(UUID persistedFaceId) { } /** - * Get the userData value. + * Get user-provided data attached to the face. The size limit is 1KB. * * @return the userData value */ @@ -59,7 +59,7 @@ public String userData() { } /** - * Set the userData value. + * Set user-provided data attached to the face. The size limit is 1KB. * * @param userData the userData value to set * @return the PersistedFace object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Person.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Person.java index b98667abb262..c2ee71712aa9 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Person.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Person.java @@ -31,7 +31,7 @@ public class Person extends NameAndUserDataContract { private List persistedFaceIds; /** - * Get the personId value. + * Get personId of the target face list. * * @return the personId value */ @@ -40,7 +40,7 @@ public UUID personId() { } /** - * Set the personId value. + * Set personId of the target face list. * * @param personId the personId value to set * @return the Person object itself. @@ -51,7 +51,7 @@ public Person withPersonId(UUID personId) { } /** - * Get the persistedFaceIds value. + * Get persistedFaceIds of registered faces in the person. These persistedFaceIds are returned from Person - Add a Person Face, and will not expire. * * @return the persistedFaceIds value */ @@ -60,7 +60,7 @@ public List persistedFaceIds() { } /** - * Set the persistedFaceIds value. + * Set persistedFaceIds of registered faces in the person. These persistedFaceIds are returned from Person - Add a Person Face, and will not expire. * * @param persistedFaceIds the persistedFaceIds value to set * @return the Person object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersonGroup.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersonGroup.java index 561e6ceb7838..65b6527af7b3 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersonGroup.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/PersonGroup.java @@ -13,15 +13,15 @@ /** * Person group object. */ -public class PersonGroup extends NameAndUserDataContract { +public class PersonGroup extends MetaDataContract { /** - * PersonGroupId of the existing person groups. + * PersonGroupId of the target person group. */ @JsonProperty(value = "personGroupId", required = true) private String personGroupId; /** - * Get the personGroupId value. + * Get personGroupId of the target person group. * * @return the personGroupId value */ @@ -30,7 +30,7 @@ public String personGroupId() { } /** - * Set the personGroupId value. + * Set personGroupId of the target person group. * * @param personGroupId the personGroupId value to set * @return the PersonGroup object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/RecognitionModel.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/RecognitionModel.java new file mode 100644 index 000000000000..60bb63708865 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/RecognitionModel.java @@ -0,0 +1,41 @@ +/** + * 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.models; + +import java.util.Collection; +import com.fasterxml.jackson.annotation.JsonCreator; +import com.microsoft.rest.ExpandableStringEnum; + +/** + * Defines values for RecognitionModel. + */ +public final class RecognitionModel extends ExpandableStringEnum { + /** Static value recognition_01 for RecognitionModel. */ + public static final RecognitionModel RECOGNITION_01 = fromString("recognition_01"); + + /** Static value recognition_02 for RecognitionModel. */ + public static final RecognitionModel RECOGNITION_02 = fromString("recognition_02"); + + /** + * Creates or finds a RecognitionModel from its string representation. + * @param name a name to look for + * @return the corresponding RecognitionModel + */ + @JsonCreator + public static RecognitionModel fromString(String name) { + return fromString(name, RecognitionModel.class); + } + + /** + * @return known RecognitionModel values + */ + public static Collection values() { + return values(RecognitionModel.class); + } +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SimilarFace.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SimilarFace.java index 9fb409c689a3..9939e4a518af 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SimilarFace.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SimilarFace.java @@ -38,7 +38,7 @@ public class SimilarFace { private double confidence; /** - * Get the faceId value. + * Get faceId of candidate face when find by faceIds. faceId is created by Face - Detect and will expire 24 hours after the detection call. * * @return the faceId value */ @@ -47,7 +47,7 @@ public UUID faceId() { } /** - * Set the faceId value. + * Set faceId of candidate face when find by faceIds. faceId is created by Face - Detect and will expire 24 hours after the detection call. * * @param faceId the faceId value to set * @return the SimilarFace object itself. @@ -58,7 +58,7 @@ public SimilarFace withFaceId(UUID faceId) { } /** - * Get the persistedFaceId value. + * Get persistedFaceId of candidate face when find by faceListId. persistedFaceId in face list is persisted and will not expire. As showed in below response. * * @return the persistedFaceId value */ @@ -67,7 +67,7 @@ public UUID persistedFaceId() { } /** - * Set the persistedFaceId value. + * Set persistedFaceId of candidate face when find by faceListId. persistedFaceId in face list is persisted and will not expire. As showed in below response. * * @param persistedFaceId the persistedFaceId value to set * @return the SimilarFace object itself. @@ -78,7 +78,7 @@ public SimilarFace withPersistedFaceId(UUID persistedFaceId) { } /** - * Get the confidence value. + * Get similarity confidence of the candidate face. The higher confidence, the more similar. Range between [0,1]. * * @return the confidence value */ @@ -87,7 +87,7 @@ public double confidence() { } /** - * Set the confidence value. + * Set similarity confidence of the candidate face. The higher confidence, the more similar. Range between [0,1]. * * @param confidence the confidence value to set * @return the SimilarFace object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Snapshot.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Snapshot.java new file mode 100644 index 000000000000..f44c454146e8 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/Snapshot.java @@ -0,0 +1,214 @@ +/** + * 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.models; + +import java.util.UUID; +import java.util.List; +import org.joda.time.DateTime; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Snapshot object. + */ +public class Snapshot { + /** + * Snapshot id. + */ + @JsonProperty(value = "id", required = true) + private UUID id; + + /** + * Azure Cognitive Service Face account id of the subscriber who created + * the snapshot by Snapshot - Take. + */ + @JsonProperty(value = "account", required = true) + private String account; + + /** + * Type of the source object in the snapshot, specified by the subscriber + * who created the snapshot when calling Snapshot - Take. Currently + * FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. + * Possible values include: 'FaceList', 'LargeFaceList', + * 'LargePersonGroup', 'PersonGroup'. + */ + @JsonProperty(value = "type", required = true) + private SnapshotObjectType type; + + /** + * Array of the target Face subscription ids for the snapshot, specified by + * the user who created the snapshot when calling Snapshot - Take. For each + * snapshot, only subscriptions included in the applyScope of Snapshot - + * Take can apply it. + */ + @JsonProperty(value = "applyScope", required = true) + private List applyScope; + + /** + * User specified data about the snapshot for any purpose. Length should + * not exceed 16KB. + */ + @JsonProperty(value = "userData") + private String userData; + + /** + * A combined UTC date and time string that describes the created time of + * the snapshot. E.g. 2018-12-25T11:41:02.2331413Z. + */ + @JsonProperty(value = "createdTime", required = true) + private DateTime createdTime; + + /** + * A combined UTC date and time string that describes the last time when + * the snapshot was created or updated by Snapshot - Update. E.g. + * 2018-12-25T11:51:27.8705696Z. + */ + @JsonProperty(value = "lastUpdateTime", required = true) + private DateTime lastUpdateTime; + + /** + * Get snapshot id. + * + * @return the id value + */ + public UUID id() { + return this.id; + } + + /** + * Set snapshot id. + * + * @param id the id value to set + * @return the Snapshot object itself. + */ + public Snapshot withId(UUID id) { + this.id = id; + return this; + } + + /** + * Get azure Cognitive Service Face account id of the subscriber who created the snapshot by Snapshot - Take. + * + * @return the account value + */ + public String account() { + return this.account; + } + + /** + * Set azure Cognitive Service Face account id of the subscriber who created the snapshot by Snapshot - Take. + * + * @param account the account value to set + * @return the Snapshot object itself. + */ + public Snapshot withAccount(String account) { + this.account = account; + return this; + } + + /** + * Get type of the source object in the snapshot, specified by the subscriber who created the snapshot when calling Snapshot - Take. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup'. + * + * @return the type value + */ + public SnapshotObjectType type() { + return this.type; + } + + /** + * Set type of the source object in the snapshot, specified by the subscriber who created the snapshot when calling Snapshot - Take. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup'. + * + * @param type the type value to set + * @return the Snapshot object itself. + */ + public Snapshot withType(SnapshotObjectType type) { + this.type = type; + return this; + } + + /** + * Get array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * + * @return the applyScope value + */ + public List applyScope() { + return this.applyScope; + } + + /** + * Set array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * + * @param applyScope the applyScope value to set + * @return the Snapshot object itself. + */ + public Snapshot withApplyScope(List applyScope) { + this.applyScope = applyScope; + return this; + } + + /** + * Get user specified data about the snapshot for any purpose. Length should not exceed 16KB. + * + * @return the userData value + */ + public String userData() { + return this.userData; + } + + /** + * Set user specified data about the snapshot for any purpose. Length should not exceed 16KB. + * + * @param userData the userData value to set + * @return the Snapshot object itself. + */ + public Snapshot withUserData(String userData) { + this.userData = userData; + return this; + } + + /** + * Get a combined UTC date and time string that describes the created time of the snapshot. E.g. 2018-12-25T11:41:02.2331413Z. + * + * @return the createdTime value + */ + public DateTime createdTime() { + return this.createdTime; + } + + /** + * Set a combined UTC date and time string that describes the created time of the snapshot. E.g. 2018-12-25T11:41:02.2331413Z. + * + * @param createdTime the createdTime value to set + * @return the Snapshot object itself. + */ + public Snapshot withCreatedTime(DateTime createdTime) { + this.createdTime = createdTime; + return this; + } + + /** + * Get a combined UTC date and time string that describes the last time when the snapshot was created or updated by Snapshot - Update. E.g. 2018-12-25T11:51:27.8705696Z. + * + * @return the lastUpdateTime value + */ + public DateTime lastUpdateTime() { + return this.lastUpdateTime; + } + + /** + * Set a combined UTC date and time string that describes the last time when the snapshot was created or updated by Snapshot - Update. E.g. 2018-12-25T11:51:27.8705696Z. + * + * @param lastUpdateTime the lastUpdateTime value to set + * @return the Snapshot object itself. + */ + public Snapshot withLastUpdateTime(DateTime lastUpdateTime) { + this.lastUpdateTime = lastUpdateTime; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyHeaders.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyHeaders.java new file mode 100644 index 000000000000..08b9f045873c --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyHeaders.java @@ -0,0 +1,44 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Defines headers for Apply operation. + */ +public class SnapshotApplyHeaders { + /** + * Operation location with an operation id used to track the progress of + * applying the snapshot by OperationStatus - Get. + */ + @JsonProperty(value = "Operation-Location") + private String operationLocation; + + /** + * Get operation location with an operation id used to track the progress of applying the snapshot by OperationStatus - Get. + * + * @return the operationLocation value + */ + public String operationLocation() { + return this.operationLocation; + } + + /** + * Set operation location with an operation id used to track the progress of applying the snapshot by OperationStatus - Get. + * + * @param operationLocation the operationLocation value to set + * @return the SnapshotApplyHeaders object itself. + */ + public SnapshotApplyHeaders withOperationLocation(String operationLocation) { + this.operationLocation = operationLocation; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyMode.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyMode.java new file mode 100644 index 000000000000..cf6885e07ce7 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotApplyMode.java @@ -0,0 +1,50 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonValue; + +/** + * Defines values for SnapshotApplyMode. + */ +public enum SnapshotApplyMode { + /** Enum value CreateNew. */ + CREATE_NEW("CreateNew"); + + /** The actual serialized value for a SnapshotApplyMode instance. */ + private String value; + + SnapshotApplyMode(String value) { + this.value = value; + } + + /** + * Parses a serialized value to a SnapshotApplyMode instance. + * + * @param value the serialized value to parse. + * @return the parsed SnapshotApplyMode object, or null if unable to parse. + */ + @JsonCreator + public static SnapshotApplyMode fromString(String value) { + SnapshotApplyMode[] items = SnapshotApplyMode.values(); + for (SnapshotApplyMode item : items) { + if (item.toString().equalsIgnoreCase(value)) { + return item; + } + } + return null; + } + + @JsonValue + @Override + public String toString() { + return this.value; + } +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotObjectType.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotObjectType.java new file mode 100644 index 000000000000..b487afccad04 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotObjectType.java @@ -0,0 +1,59 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonCreator; +import com.fasterxml.jackson.annotation.JsonValue; + +/** + * Defines values for SnapshotObjectType. + */ +public enum SnapshotObjectType { + /** Enum value FaceList. */ + FACE_LIST("FaceList"), + + /** Enum value LargeFaceList. */ + LARGE_FACE_LIST("LargeFaceList"), + + /** Enum value LargePersonGroup. */ + LARGE_PERSON_GROUP("LargePersonGroup"), + + /** Enum value PersonGroup. */ + PERSON_GROUP("PersonGroup"); + + /** The actual serialized value for a SnapshotObjectType instance. */ + private String value; + + SnapshotObjectType(String value) { + this.value = value; + } + + /** + * Parses a serialized value to a SnapshotObjectType instance. + * + * @param value the serialized value to parse. + * @return the parsed SnapshotObjectType object, or null if unable to parse. + */ + @JsonCreator + public static SnapshotObjectType fromString(String value) { + SnapshotObjectType[] items = SnapshotObjectType.values(); + for (SnapshotObjectType item : items) { + if (item.toString().equalsIgnoreCase(value)) { + return item; + } + } + return null; + } + + @JsonValue + @Override + public String toString() { + return this.value; + } +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotTakeHeaders.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotTakeHeaders.java new file mode 100644 index 000000000000..6a7f95c05199 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/SnapshotTakeHeaders.java @@ -0,0 +1,46 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Defines headers for Take operation. + */ +public class SnapshotTakeHeaders { + /** + * Operation location with an operation id used to track the progress of + * taking snapshot. The returned id is the operation id, rather than + * snapshot id. Snapshot id can be obtained only when the operation status + * becomes "succeeded" in OperationStatus - Get. + */ + @JsonProperty(value = "Operation-Location") + private String operationLocation; + + /** + * Get operation location with an operation id used to track the progress of taking snapshot. The returned id is the operation id, rather than snapshot id. Snapshot id can be obtained only when the operation status becomes "succeeded" in OperationStatus - Get. + * + * @return the operationLocation value + */ + public String operationLocation() { + return this.operationLocation; + } + + /** + * Set operation location with an operation id used to track the progress of taking snapshot. The returned id is the operation id, rather than snapshot id. Snapshot id can be obtained only when the operation status becomes "succeeded" in OperationStatus - Get. + * + * @param operationLocation the operationLocation value to set + * @return the SnapshotTakeHeaders object itself. + */ + public SnapshotTakeHeaders withOperationLocation(String operationLocation) { + this.operationLocation = operationLocation; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TakeSnapshotRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TakeSnapshotRequest.java new file mode 100644 index 000000000000..0fcb328904f0 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TakeSnapshotRequest.java @@ -0,0 +1,129 @@ +/** + * 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.models; + +import java.util.List; +import java.util.UUID; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Request body for taking snapshot operation. + */ +public class TakeSnapshotRequest { + /** + * User specified type for the source object to take snapshot from. + * Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are + * supported. Possible values include: 'FaceList', 'LargeFaceList', + * 'LargePersonGroup', 'PersonGroup'. + */ + @JsonProperty(value = "type", required = true) + private SnapshotObjectType type; + + /** + * User specified source object id to take snapshot from. + */ + @JsonProperty(value = "objectId", required = true) + private String objectId; + + /** + * User specified array of target Face subscription ids for the snapshot. + * For each snapshot, only subscriptions included in the applyScope of + * Snapshot - Take can apply it. + */ + @JsonProperty(value = "applyScope", required = true) + private List applyScope; + + /** + * User specified data about the snapshot for any purpose. Length should + * not exceed 16KB. + */ + @JsonProperty(value = "userData") + private String userData; + + /** + * Get user specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup'. + * + * @return the type value + */ + public SnapshotObjectType type() { + return this.type; + } + + /** + * Set user specified type for the source object to take snapshot from. Currently FaceList, PersonGroup, LargeFaceList and LargePersonGroup are supported. Possible values include: 'FaceList', 'LargeFaceList', 'LargePersonGroup', 'PersonGroup'. + * + * @param type the type value to set + * @return the TakeSnapshotRequest object itself. + */ + public TakeSnapshotRequest withType(SnapshotObjectType type) { + this.type = type; + return this; + } + + /** + * Get user specified source object id to take snapshot from. + * + * @return the objectId value + */ + public String objectId() { + return this.objectId; + } + + /** + * Set user specified source object id to take snapshot from. + * + * @param objectId the objectId value to set + * @return the TakeSnapshotRequest object itself. + */ + public TakeSnapshotRequest withObjectId(String objectId) { + this.objectId = objectId; + return this; + } + + /** + * Get user specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * + * @return the applyScope value + */ + public List applyScope() { + return this.applyScope; + } + + /** + * Set user specified array of target Face subscription ids for the snapshot. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * + * @param applyScope the applyScope value to set + * @return the TakeSnapshotRequest object itself. + */ + public TakeSnapshotRequest withApplyScope(List applyScope) { + this.applyScope = applyScope; + return this; + } + + /** + * Get user specified data about the snapshot for any purpose. Length should not exceed 16KB. + * + * @return the userData value + */ + public String userData() { + return this.userData; + } + + /** + * Set user specified data about the snapshot for any purpose. Length should not exceed 16KB. + * + * @param userData the userData value to set + * @return the TakeSnapshotRequest object itself. + */ + public TakeSnapshotRequest withUserData(String userData) { + this.userData = userData; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TrainingStatus.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TrainingStatus.java index c80730f3617d..9c0ff492b7a0 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TrainingStatus.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/TrainingStatus.java @@ -19,27 +19,38 @@ public class TrainingStatus { * Training status: notstarted, running, succeeded, failed. If the training * process is waiting to perform, the status is notstarted. If the training * is ongoing, the status is running. Status succeed means this person - * group is ready for Face - Identify. Status failed is often caused by no - * person or no persisted face exist in the person group. Possible values - * include: 'nonstarted', 'running', 'succeeded', 'failed'. + * group or large person group is ready for Face - Identify, or this large + * face list is ready for Face - Find Similar. Status failed is often + * caused by no person or no persisted face exist in the person group or + * large person group, or no persisted face exist in the large face list. + * Possible values include: 'nonstarted', 'running', 'succeeded', 'failed'. */ @JsonProperty(value = "status", required = true) private TrainingStatusType status; /** - * A combined UTC date and time string that describes person group created - * time. + * A combined UTC date and time string that describes the created time of + * the person group, large person group or large face list. */ @JsonProperty(value = "createdDateTime", required = true) private DateTime created; /** - * Person group last modify time in the UTC, could be null value when the - * person group is not successfully trained. + * A combined UTC date and time string that describes the last modify time + * of the person group, large person group or large face list, could be + * null value when the group is not successfully trained. */ @JsonProperty(value = "lastActionDateTime") private DateTime lastAction; + /** + * A combined UTC date and time string that describes the last successful + * training time of the person group, large person group or large face + * list. + */ + @JsonProperty(value = "lastSuccessfulTrainingDateTime") + private DateTime lastSuccessfulTraining; + /** * Show failure message when training failed (omitted when training * succeed). @@ -48,7 +59,7 @@ public class TrainingStatus { private String message; /** - * Get the status value. + * Get training status: notstarted, running, succeeded, failed. If the training process is waiting to perform, the status is notstarted. If the training is ongoing, the status is running. Status succeed means this person group or large person group is ready for Face - Identify, or this large face list is ready for Face - Find Similar. Status failed is often caused by no person or no persisted face exist in the person group or large person group, or no persisted face exist in the large face list. Possible values include: 'nonstarted', 'running', 'succeeded', 'failed'. * * @return the status value */ @@ -57,7 +68,7 @@ public TrainingStatusType status() { } /** - * Set the status value. + * Set training status: notstarted, running, succeeded, failed. If the training process is waiting to perform, the status is notstarted. If the training is ongoing, the status is running. Status succeed means this person group or large person group is ready for Face - Identify, or this large face list is ready for Face - Find Similar. Status failed is often caused by no person or no persisted face exist in the person group or large person group, or no persisted face exist in the large face list. Possible values include: 'nonstarted', 'running', 'succeeded', 'failed'. * * @param status the status value to set * @return the TrainingStatus object itself. @@ -68,7 +79,7 @@ public TrainingStatus withStatus(TrainingStatusType status) { } /** - * Get the created value. + * Get a combined UTC date and time string that describes the created time of the person group, large person group or large face list. * * @return the created value */ @@ -77,7 +88,7 @@ public DateTime created() { } /** - * Set the created value. + * Set a combined UTC date and time string that describes the created time of the person group, large person group or large face list. * * @param created the created value to set * @return the TrainingStatus object itself. @@ -88,7 +99,7 @@ public TrainingStatus withCreated(DateTime created) { } /** - * Get the lastAction value. + * Get a combined UTC date and time string that describes the last modify time of the person group, large person group or large face list, could be null value when the group is not successfully trained. * * @return the lastAction value */ @@ -97,7 +108,7 @@ public DateTime lastAction() { } /** - * Set the lastAction value. + * Set a combined UTC date and time string that describes the last modify time of the person group, large person group or large face list, could be null value when the group is not successfully trained. * * @param lastAction the lastAction value to set * @return the TrainingStatus object itself. @@ -108,7 +119,27 @@ public TrainingStatus withLastAction(DateTime lastAction) { } /** - * Get the message value. + * Get a combined UTC date and time string that describes the last successful training time of the person group, large person group or large face list. + * + * @return the lastSuccessfulTraining value + */ + public DateTime lastSuccessfulTraining() { + return this.lastSuccessfulTraining; + } + + /** + * Set a combined UTC date and time string that describes the last successful training time of the person group, large person group or large face list. + * + * @param lastSuccessfulTraining the lastSuccessfulTraining value to set + * @return the TrainingStatus object itself. + */ + public TrainingStatus withLastSuccessfulTraining(DateTime lastSuccessfulTraining) { + this.lastSuccessfulTraining = lastSuccessfulTraining; + return this; + } + + /** + * Get show failure message when training failed (omitted when training succeed). * * @return the message value */ @@ -117,7 +148,7 @@ public String message() { } /** - * Set the message value. + * Set show failure message when training failed (omitted when training succeed). * * @param message the message value to set * @return the TrainingStatus object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateFaceRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateFaceRequest.java new file mode 100644 index 000000000000..94b1020f33b9 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateFaceRequest.java @@ -0,0 +1,43 @@ +/** + * 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.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Request to update face data. + */ +public class UpdateFaceRequest { + /** + * User-provided data attached to the face. The size limit is 1KB. + */ + @JsonProperty(value = "userData") + private String userData; + + /** + * Get user-provided data attached to the face. The size limit is 1KB. + * + * @return the userData value + */ + public String userData() { + return this.userData; + } + + /** + * Set user-provided data attached to the face. The size limit is 1KB. + * + * @param userData the userData value to set + * @return the UpdateFaceRequest object itself. + */ + public UpdateFaceRequest withUserData(String userData) { + this.userData = userData; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateSnapshotRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateSnapshotRequest.java new file mode 100644 index 000000000000..cc23208d61a6 --- /dev/null +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/UpdateSnapshotRequest.java @@ -0,0 +1,76 @@ +/** + * 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.models; + +import java.util.List; +import java.util.UUID; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Request body for updating a snapshot, with a combination of user defined + * apply scope and user specified data. + */ +public class UpdateSnapshotRequest { + /** + * Array of the target Face subscription ids for the snapshot, specified by + * the user who created the snapshot when calling Snapshot - Take. For each + * snapshot, only subscriptions included in the applyScope of Snapshot - + * Take can apply it. + */ + @JsonProperty(value = "applyScope") + private List applyScope; + + /** + * User specified data about the snapshot for any purpose. Length should + * not exceed 16KB. + */ + @JsonProperty(value = "userData") + private String userData; + + /** + * Get array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * + * @return the applyScope value + */ + public List applyScope() { + return this.applyScope; + } + + /** + * Set array of the target Face subscription ids for the snapshot, specified by the user who created the snapshot when calling Snapshot - Take. For each snapshot, only subscriptions included in the applyScope of Snapshot - Take can apply it. + * + * @param applyScope the applyScope value to set + * @return the UpdateSnapshotRequest object itself. + */ + public UpdateSnapshotRequest withApplyScope(List applyScope) { + this.applyScope = applyScope; + return this; + } + + /** + * Get user specified data about the snapshot for any purpose. Length should not exceed 16KB. + * + * @return the userData value + */ + public String userData() { + return this.userData; + } + + /** + * Set user specified data about the snapshot for any purpose. Length should not exceed 16KB. + * + * @param userData the userData value to set + * @return the UpdateSnapshotRequest object itself. + */ + public UpdateSnapshotRequest withUserData(String userData) { + this.userData = userData; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToFaceRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToFaceRequest.java index c38465fcc0fc..5696325adf75 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToFaceRequest.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToFaceRequest.java @@ -12,7 +12,7 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * Request body for verify operation. + * Request body for face to face verification. */ public class VerifyFaceToFaceRequest { /** @@ -28,7 +28,7 @@ public class VerifyFaceToFaceRequest { private UUID faceId2; /** - * Get the faceId1 value. + * Get faceId of the first face, comes from Face - Detect. * * @return the faceId1 value */ @@ -37,7 +37,7 @@ public UUID faceId1() { } /** - * Set the faceId1 value. + * Set faceId of the first face, comes from Face - Detect. * * @param faceId1 the faceId1 value to set * @return the VerifyFaceToFaceRequest object itself. @@ -48,7 +48,7 @@ public VerifyFaceToFaceRequest withFaceId1(UUID faceId1) { } /** - * Get the faceId2 value. + * Get faceId of the second face, comes from Face - Detect. * * @return the faceId2 value */ @@ -57,7 +57,7 @@ public UUID faceId2() { } /** - * Set the faceId2 value. + * Set faceId of the second face, comes from Face - Detect. * * @param faceId2 the faceId2 value to set * @return the VerifyFaceToFaceRequest object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToPersonRequest.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToPersonRequest.java index 69cfa7b70ccd..5758d82d4a93 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToPersonRequest.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyFaceToPersonRequest.java @@ -12,31 +12,43 @@ import com.fasterxml.jackson.annotation.JsonProperty; /** - * Request body for verify operation. + * Request body for face to person verification. */ public class VerifyFaceToPersonRequest { /** - * FaceId the face, comes from Face - Detect. + * FaceId of the face, comes from Face - Detect. */ @JsonProperty(value = "faceId", required = true) private UUID faceId; /** * Using existing personGroupId and personId for fast loading a specified - * person. personGroupId is created in Person Groups.Create. + * person. personGroupId is created in PersonGroup - Create. Parameter + * personGroupId and largePersonGroupId should not be provided at the same + * time. */ - @JsonProperty(value = "personGroupId", required = true) + @JsonProperty(value = "personGroupId") private String personGroupId; /** - * Specify a certain person in a person group. personId is created in - * Persons.Create. + * Using existing largePersonGroupId and personId for fast loading a + * specified person. largePersonGroupId is created in LargePersonGroup - + * Create. Parameter personGroupId and largePersonGroupId should not be + * provided at the same time. + */ + @JsonProperty(value = "largePersonGroupId") + private String largePersonGroupId; + + /** + * Specify a certain person in a person group or a large person group. + * personId is created in PersonGroup Person - Create or LargePersonGroup + * Person - Create. */ @JsonProperty(value = "personId", required = true) private UUID personId; /** - * Get the faceId value. + * Get faceId of the face, comes from Face - Detect. * * @return the faceId value */ @@ -45,7 +57,7 @@ public UUID faceId() { } /** - * Set the faceId value. + * Set faceId of the face, comes from Face - Detect. * * @param faceId the faceId value to set * @return the VerifyFaceToPersonRequest object itself. @@ -56,7 +68,7 @@ public VerifyFaceToPersonRequest withFaceId(UUID faceId) { } /** - * Get the personGroupId value. + * Get using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * * @return the personGroupId value */ @@ -65,7 +77,7 @@ public String personGroupId() { } /** - * Set the personGroupId value. + * Set using existing personGroupId and personId for fast loading a specified person. personGroupId is created in PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. * * @param personGroupId the personGroupId value to set * @return the VerifyFaceToPersonRequest object itself. @@ -76,7 +88,27 @@ public VerifyFaceToPersonRequest withPersonGroupId(String personGroupId) { } /** - * Get the personId value. + * Get using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * + * @return the largePersonGroupId value + */ + public String largePersonGroupId() { + return this.largePersonGroupId; + } + + /** + * Set using existing largePersonGroupId and personId for fast loading a specified person. largePersonGroupId is created in LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. + * + * @param largePersonGroupId the largePersonGroupId value to set + * @return the VerifyFaceToPersonRequest object itself. + */ + public VerifyFaceToPersonRequest withLargePersonGroupId(String largePersonGroupId) { + this.largePersonGroupId = largePersonGroupId; + return this; + } + + /** + * Get specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. * * @return the personId value */ @@ -85,7 +117,7 @@ public UUID personId() { } /** - * Set the personId value. + * Set specify a certain person in a person group or a large person group. personId is created in PersonGroup Person - Create or LargePersonGroup Person - Create. * * @param personId the personId value to set * @return the VerifyFaceToPersonRequest object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyResult.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyResult.java index df17ae94bc5d..01b2167c8110 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyResult.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/VerifyResult.java @@ -32,7 +32,7 @@ public class VerifyResult { private double confidence; /** - * Get the isIdentical value. + * Get true if the two faces belong to the same person or the face belongs to the person, otherwise false. * * @return the isIdentical value */ @@ -41,7 +41,7 @@ public boolean isIdentical() { } /** - * Set the isIdentical value. + * Set true if the two faces belong to the same person or the face belongs to the person, otherwise false. * * @param isIdentical the isIdentical value to set * @return the VerifyResult object itself. @@ -52,7 +52,7 @@ public VerifyResult withIsIdentical(boolean isIdentical) { } /** - * Get the confidence value. + * Get a number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person. By default, isIdentical is set to True if similarity confidence is greater than or equal to 0.5. This is useful for advanced users to override "isIdentical" and fine-tune the result on their own data. * * @return the confidence value */ @@ -61,7 +61,7 @@ public double confidence() { } /** - * Set the confidence value. + * Set a number indicates the similarity confidence of whether two faces belong to the same person, or whether the face belongs to the person. By default, isIdentical is set to True if similarity confidence is greater than or equal to 0.5. This is useful for advanced users to override "isIdentical" and fine-tune the result on their own data. * * @param confidence the confidence value to set * @return the VerifyResult object itself. diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/package-info.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/package-info.java index acb4d1e307af..2e540da66484 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/package-info.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/models/package-info.java @@ -5,7 +5,7 @@ // Code generated by Microsoft (R) AutoRest Code Generator. /** - * This package contains the models classes for FaceAPI. + * This package contains the models classes for FaceClient. * An API for face detection, verification, and identification. */ package com.microsoft.azure.cognitiveservices.vision.faceapi.models; diff --git a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/package-info.java b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/package-info.java index 9266ae52be91..6a7b6a2a05a4 100644 --- a/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/package-info.java +++ b/cognitiveservices/data-plane/vision/faceapi/src/main/java/com/microsoft/azure/cognitiveservices/vision/faceapi/package-info.java @@ -5,7 +5,7 @@ // Code generated by Microsoft (R) AutoRest Code Generator. /** - * This package contains the classes for FaceAPI. + * This package contains the classes for FaceClient. * An API for face detection, verification, and identification. */ package com.microsoft.azure.cognitiveservices.vision.faceapi; diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/CognitiveServiceFormRecognizerAPIV1Preview.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/CognitiveServiceFormRecognizerAPIV1Preview.java new file mode 100644 index 000000000000..8deba5e4d6cc --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/CognitiveServiceFormRecognizerAPIV1Preview.java @@ -0,0 +1,430 @@ +/** + * 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.formrecognizer; + +import com.microsoft.azure.AzureClient; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.AnalyzeResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ErrorResponseException; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.KeysResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelsResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.TrainResult; +import com.microsoft.rest.RestClient; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import rx.Observable; + +/** + * The interface for CognitiveServiceFormRecognizerAPIV1Preview class. + */ +public interface CognitiveServiceFormRecognizerAPIV1Preview { + /** + * Gets the REST client. + * + * @return the {@link RestClient} object. + */ + RestClient restClient(); + + /** + * Gets the {@link AzureClient} used for long running operations. + * @return the azure client; + */ + AzureClient getAzureClient(); + + /** + * Gets the User-Agent header for the client. + * + * @return the user agent string. + */ + String userAgent(); + + /** + * Gets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).. + * + * @return the endpoint value. + */ + String endpoint(); + + /** + * Sets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).. + * + * @param endpoint the endpoint value. + * @return the service client itself + */ + CognitiveServiceFormRecognizerAPIV1Preview withEndpoint(String endpoint); + + /** + * Gets The preferred language for the response.. + * + * @return the acceptLanguage value. + */ + String acceptLanguage(); + + /** + * Sets The preferred language for the response.. + * + * @param acceptLanguage the acceptLanguage value. + * @return the service client itself + */ + CognitiveServiceFormRecognizerAPIV1Preview withAcceptLanguage(String acceptLanguage); + + /** + * Gets The retry timeout in seconds for Long Running Operations. Default value is 30.. + * + * @return the longRunningOperationRetryTimeout value. + */ + int longRunningOperationRetryTimeout(); + + /** + * Sets The retry timeout in seconds for Long Running Operations. Default value is 30.. + * + * @param longRunningOperationRetryTimeout the longRunningOperationRetryTimeout value. + * @return the service client itself + */ + CognitiveServiceFormRecognizerAPIV1Preview withLongRunningOperationRetryTimeout(int longRunningOperationRetryTimeout); + + /** + * Gets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true.. + * + * @return the generateClientRequestId value. + */ + boolean generateClientRequestId(); + + /** + * Sets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true.. + * + * @param generateClientRequestId the generateClientRequestId value. + * @return the service client itself + */ + CognitiveServiceFormRecognizerAPIV1Preview withGenerateClientRequestId(boolean generateClientRequestId); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the TrainResult object if successful. + */ + TrainResult trainCustomModel(String source); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture trainCustomModelAsync(String source, final ServiceCallback serviceCallback); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + Observable trainCustomModelAsync(String source); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + Observable> trainCustomModelWithServiceResponseAsync(String source); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the KeysResult object if successful. + */ + KeysResult getExtractedKeys(UUID id); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getExtractedKeysAsync(UUID id, final ServiceCallback serviceCallback); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + Observable getExtractedKeysAsync(UUID id); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + Observable> getExtractedKeysWithServiceResponseAsync(UUID id); + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelsResult object if successful. + */ + ModelsResult getCustomModels(); + + /** + * Get Models. + * Get information about all trained models. + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getCustomModelsAsync(final ServiceCallback serviceCallback); + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + Observable getCustomModelsAsync(); + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + Observable> getCustomModelsWithServiceResponseAsync(); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelResult object if successful. + */ + ModelResult getCustomModel(UUID id); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getCustomModelAsync(UUID id, final ServiceCallback serviceCallback); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + Observable getCustomModelAsync(UUID id); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + Observable> getCustomModelWithServiceResponseAsync(UUID id); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + */ + void deleteCustomModel(UUID id); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteCustomModelAsync(UUID id, final ServiceCallback serviceCallback); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteCustomModelAsync(UUID id); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteCustomModelWithServiceResponseAsync(UUID id); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, final ServiceCallback serviceCallback); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream); + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream, List keys); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys, final ServiceCallback serviceCallback); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream, List keys); + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/CognitiveServiceFormRecognizerAPIV1PreviewImpl.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/CognitiveServiceFormRecognizerAPIV1PreviewImpl.java new file mode 100644 index 000000000000..26376f7072ef --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/CognitiveServiceFormRecognizerAPIV1PreviewImpl.java @@ -0,0 +1,829 @@ +/** + * 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.formrecognizer.implementation; + +import com.google.common.base.Joiner; +import com.google.common.reflect.TypeToken; +import com.microsoft.azure.AzureClient; +import com.microsoft.azure.AzureServiceClient; +import com.microsoft.azure.cognitiveservices.formrecognizer.CognitiveServiceFormRecognizerAPIV1Preview; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.AnalyzeResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ErrorResponseException; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.KeysResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelsResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.TrainRequest; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.TrainResult; +import com.microsoft.rest.CollectionFormat; +import com.microsoft.rest.credentials.ServiceClientCredentials; +import com.microsoft.rest.RestClient; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import com.microsoft.rest.Validator; +import java.io.InputStream; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import okhttp3.ResponseBody; +import retrofit2.http.Body; +import retrofit2.http.GET; +import retrofit2.http.Header; +import retrofit2.http.Headers; +import retrofit2.http.HTTP; +import retrofit2.http.Multipart; +import retrofit2.http.Part; +import retrofit2.http.Path; +import retrofit2.http.POST; +import retrofit2.http.Query; +import retrofit2.Response; +import rx.functions.Func1; +import rx.Observable; + +/** + * Initializes a new instance of the CognitiveServiceFormRecognizerAPIV1PreviewImpl class. + */ +public class CognitiveServiceFormRecognizerAPIV1PreviewImpl extends AzureServiceClient implements CognitiveServiceFormRecognizerAPIV1Preview { + /** The Retrofit service to perform REST calls. */ + private CognitiveServiceFormRecognizerAPIV1PreviewService service; + /** the {@link AzureClient} used for long running operations. */ + private AzureClient azureClient; + + /** + * Gets the {@link AzureClient} used for long running operations. + * @return the azure client; + */ + public AzureClient getAzureClient() { + return this.azureClient; + } + + /** Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com). */ + private String endpoint; + + /** + * Gets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com). + * + * @return the endpoint value. + */ + public String endpoint() { + return this.endpoint; + } + + /** + * Sets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com). + * + * @param endpoint the endpoint value. + * @return the service client itself + */ + public CognitiveServiceFormRecognizerAPIV1PreviewImpl withEndpoint(String endpoint) { + this.endpoint = endpoint; + return this; + } + + /** The preferred language for the response. */ + private String acceptLanguage; + + /** + * Gets The preferred language for the response. + * + * @return the acceptLanguage value. + */ + public String acceptLanguage() { + return this.acceptLanguage; + } + + /** + * Sets The preferred language for the response. + * + * @param acceptLanguage the acceptLanguage value. + * @return the service client itself + */ + public CognitiveServiceFormRecognizerAPIV1PreviewImpl withAcceptLanguage(String acceptLanguage) { + this.acceptLanguage = acceptLanguage; + return this; + } + + /** The retry timeout in seconds for Long Running Operations. Default value is 30. */ + private int longRunningOperationRetryTimeout; + + /** + * Gets The retry timeout in seconds for Long Running Operations. Default value is 30. + * + * @return the longRunningOperationRetryTimeout value. + */ + public int longRunningOperationRetryTimeout() { + return this.longRunningOperationRetryTimeout; + } + + /** + * Sets The retry timeout in seconds for Long Running Operations. Default value is 30. + * + * @param longRunningOperationRetryTimeout the longRunningOperationRetryTimeout value. + * @return the service client itself + */ + public CognitiveServiceFormRecognizerAPIV1PreviewImpl withLongRunningOperationRetryTimeout(int longRunningOperationRetryTimeout) { + this.longRunningOperationRetryTimeout = longRunningOperationRetryTimeout; + return this; + } + + /** Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. */ + private boolean generateClientRequestId; + + /** + * Gets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. + * + * @return the generateClientRequestId value. + */ + public boolean generateClientRequestId() { + return this.generateClientRequestId; + } + + /** + * Sets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. + * + * @param generateClientRequestId the generateClientRequestId value. + * @return the service client itself + */ + public CognitiveServiceFormRecognizerAPIV1PreviewImpl withGenerateClientRequestId(boolean generateClientRequestId) { + this.generateClientRequestId = generateClientRequestId; + return this; + } + + /** + * Initializes an instance of CognitiveServiceFormRecognizerAPIV1Preview client. + * + * @param credentials the management credentials for Azure + */ + public CognitiveServiceFormRecognizerAPIV1PreviewImpl(ServiceClientCredentials credentials) { + this("https://{Endpoint}/formrecognizer/v1.0-preview", credentials); + } + + /** + * Initializes an instance of CognitiveServiceFormRecognizerAPIV1Preview client. + * + * @param baseUrl the base URL of the host + * @param credentials the management credentials for Azure + */ + private CognitiveServiceFormRecognizerAPIV1PreviewImpl(String baseUrl, ServiceClientCredentials credentials) { + super(baseUrl, credentials); + initialize(); + } + + /** + * Initializes an instance of CognitiveServiceFormRecognizerAPIV1Preview client. + * + * @param restClient the REST client to connect to Azure. + */ + public CognitiveServiceFormRecognizerAPIV1PreviewImpl(RestClient restClient) { + super(restClient); + initialize(); + } + + protected void initialize() { + this.acceptLanguage = "en-US"; + this.longRunningOperationRetryTimeout = 30; + this.generateClientRequestId = true; + this.azureClient = new AzureClient(this); + initializeService(); + } + + /** + * Gets the User-Agent header for the client. + * + * @return the user agent string. + */ + @Override + public String userAgent() { + return String.format("%s (%s, %s)", super.userAgent(), "CognitiveServiceFormRecognizerAPIV1Preview", "v1.0-preview"); + } + + private void initializeService() { + service = restClient().retrofit().create(CognitiveServiceFormRecognizerAPIV1PreviewService.class); + } + + /** + * The interface defining all the services for CognitiveServiceFormRecognizerAPIV1Preview to be + * used by Retrofit to perform actually REST calls. + */ + interface CognitiveServiceFormRecognizerAPIV1PreviewService { + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.CognitiveServiceFormRecognizerAPIV1Preview trainCustomModel" }) + @POST("custom/train") + Observable> trainCustomModel(@Header("accept-language") String acceptLanguage, @Body TrainRequest trainRequest, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.CognitiveServiceFormRecognizerAPIV1Preview getExtractedKeys" }) + @GET("custom/models/{id}/keys") + Observable> getExtractedKeys(@Path("id") UUID id, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.CognitiveServiceFormRecognizerAPIV1Preview getCustomModels" }) + @GET("custom/models") + Observable> getCustomModels(@Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.CognitiveServiceFormRecognizerAPIV1Preview getCustomModel" }) + @GET("custom/models/{id}") + Observable> getCustomModel(@Path("id") UUID id, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.CognitiveServiceFormRecognizerAPIV1Preview deleteCustomModel" }) + @HTTP(path = "custom/models/{id}", method = "DELETE", hasBody = true) + Observable> deleteCustomModel(@Path("id") UUID id, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Multipart + @POST("custom/models/{id}/analyze") + Observable> analyzeWithCustomModel(@Path("id") UUID id, @Query("keys") String keys, @Part("form_stream") RequestBody formStream, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the TrainResult object if successful. + */ + public TrainResult trainCustomModel(String source) { + return trainCustomModelWithServiceResponseAsync(source).toBlocking().single().body(); + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture trainCustomModelAsync(String source, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(trainCustomModelWithServiceResponseAsync(source), serviceCallback); + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + public Observable trainCustomModelAsync(String source) { + return trainCustomModelWithServiceResponseAsync(source).map(new Func1, TrainResult>() { + @Override + public TrainResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + public Observable> trainCustomModelWithServiceResponseAsync(String source) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (source == null) { + throw new IllegalArgumentException("Parameter source is required and cannot be null."); + } + TrainRequest trainRequest = new TrainRequest(); + trainRequest.withSource(source); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.trainCustomModel(this.acceptLanguage(), trainRequest, parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = trainCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse trainCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the KeysResult object if successful. + */ + public KeysResult getExtractedKeys(UUID id) { + return getExtractedKeysWithServiceResponseAsync(id).toBlocking().single().body(); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getExtractedKeysAsync(UUID id, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getExtractedKeysWithServiceResponseAsync(id), serviceCallback); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + public Observable getExtractedKeysAsync(UUID id) { + return getExtractedKeysWithServiceResponseAsync(id).map(new Func1, KeysResult>() { + @Override + public KeysResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + public Observable> getExtractedKeysWithServiceResponseAsync(UUID id) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.getExtractedKeys(id, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getExtractedKeysDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getExtractedKeysDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelsResult object if successful. + */ + public ModelsResult getCustomModels() { + return getCustomModelsWithServiceResponseAsync().toBlocking().single().body(); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getCustomModelsAsync(final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getCustomModelsWithServiceResponseAsync(), serviceCallback); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + public Observable getCustomModelsAsync() { + return getCustomModelsWithServiceResponseAsync().map(new Func1, ModelsResult>() { + @Override + public ModelsResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + public Observable> getCustomModelsWithServiceResponseAsync() { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.getCustomModels(this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getCustomModelsDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getCustomModelsDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelResult object if successful. + */ + public ModelResult getCustomModel(UUID id) { + return getCustomModelWithServiceResponseAsync(id).toBlocking().single().body(); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getCustomModelAsync(UUID id, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getCustomModelWithServiceResponseAsync(id), serviceCallback); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + public Observable getCustomModelAsync(UUID id) { + return getCustomModelWithServiceResponseAsync(id).map(new Func1, ModelResult>() { + @Override + public ModelResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + public Observable> getCustomModelWithServiceResponseAsync(UUID id) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.getCustomModel(id, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + */ + public void deleteCustomModel(UUID id) { + deleteCustomModelWithServiceResponseAsync(id).toBlocking().single().body(); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteCustomModelAsync(UUID id, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteCustomModelWithServiceResponseAsync(id), serviceCallback); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteCustomModelAsync(UUID id) { + return deleteCustomModelWithServiceResponseAsync(id).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteCustomModelWithServiceResponseAsync(UUID id) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.deleteCustomModel(id, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(204, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + public AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream).toBlocking().single().body(); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(analyzeWithCustomModelWithServiceResponseAsync(id, formStream), serviceCallback); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream).map(new Func1, AnalyzeResult>() { + @Override + public AnalyzeResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + if (formStream == null) { + throw new IllegalArgumentException("Parameter formStream is required and cannot be null."); + } + final List keys = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + String keysConverted = this.serializerAdapter().serializeList(keys, CollectionFormat.CSV);RequestBody formStreamConverted = RequestBody.create(MediaType.parse("multipart/form-data"), formStream); + return service.analyzeWithCustomModel(id, keysConverted, formStreamConverted, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = analyzeWithCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + public AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream, List keys) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream, keys).toBlocking().single().body(); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(analyzeWithCustomModelWithServiceResponseAsync(id, formStream, keys), serviceCallback); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream, keys).map(new Func1, AnalyzeResult>() { + @Override + public AnalyzeResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream, List keys) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + if (formStream == null) { + throw new IllegalArgumentException("Parameter formStream is required and cannot be null."); + } + Validator.validate(keys); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + String keysConverted = this.serializerAdapter().serializeList(keys, CollectionFormat.CSV);RequestBody formStreamConverted = RequestBody.create(MediaType.parse("multipart/form-data"), formStream); + return service.analyzeWithCustomModel(id, keysConverted, formStreamConverted, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = analyzeWithCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse analyzeWithCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java new file mode 100644 index 000000000000..56bcefa64381 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java @@ -0,0 +1,11 @@ +// 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. + +/** + * This package contains the implementation classes for CognitiveServiceFormRecognizerAPIV1Preview. + * Extracts information from forms and images into structured data based on a model created by a set of representative training forms. + */ +package com.microsoft.azure.cognitiveservices.formrecognizer.implementation; diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/AnalyzeResult.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/AnalyzeResult.java new file mode 100644 index 000000000000..fa97fbb84e87 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/AnalyzeResult.java @@ -0,0 +1,103 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Analyze API call result. + */ +public class AnalyzeResult { + /** + * Status of the analyze operation. Possible values include: 'success', + * 'partialSuccess', 'failure'. + */ + @JsonProperty(value = "status") + private String status; + + /** + * Page level information extracted in the analyzed + * document. + */ + @JsonProperty(value = "pages") + private List pages; + + /** + * List of errors reported during the analyze + * operation. + */ + @JsonProperty(value = "errors") + private List errors; + + /** + * Get status of the analyze operation. Possible values include: 'success', 'partialSuccess', 'failure'. + * + * @return the status value + */ + public String status() { + return this.status; + } + + /** + * Set status of the analyze operation. Possible values include: 'success', 'partialSuccess', 'failure'. + * + * @param status the status value to set + * @return the AnalyzeResult object itself. + */ + public AnalyzeResult withStatus(String status) { + this.status = status; + return this; + } + + /** + * Get page level information extracted in the analyzed + document. + * + * @return the pages value + */ + public List pages() { + return this.pages; + } + + /** + * Set page level information extracted in the analyzed + document. + * + * @param pages the pages value to set + * @return the AnalyzeResult object itself. + */ + public AnalyzeResult withPages(List pages) { + this.pages = pages; + return this; + } + + /** + * Get list of errors reported during the analyze + operation. + * + * @return the errors value + */ + public List errors() { + return this.errors; + } + + /** + * Set list of errors reported during the analyze + operation. + * + * @param errors the errors value to set + * @return the AnalyzeResult object itself. + */ + public AnalyzeResult withErrors(List errors) { + this.errors = errors; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorInformation.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorInformation.java new file mode 100644 index 000000000000..edf56120531a --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorInformation.java @@ -0,0 +1,95 @@ +/** + * 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.formrecognizer.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * The ErrorInformation model. + */ +public class ErrorInformation { + /** + * The code property. + */ + @JsonProperty(value = "code") + private String code; + + /** + * The innerError property. + */ + @JsonProperty(value = "innerError") + private InnerError innerError; + + /** + * The message property. + */ + @JsonProperty(value = "message") + private String message; + + /** + * Get the code value. + * + * @return the code value + */ + public String code() { + return this.code; + } + + /** + * Set the code value. + * + * @param code the code value to set + * @return the ErrorInformation object itself. + */ + public ErrorInformation withCode(String code) { + this.code = code; + return this; + } + + /** + * Get the innerError value. + * + * @return the innerError value + */ + public InnerError innerError() { + return this.innerError; + } + + /** + * Set the innerError value. + * + * @param innerError the innerError value to set + * @return the ErrorInformation object itself. + */ + public ErrorInformation withInnerError(InnerError innerError) { + this.innerError = innerError; + return this; + } + + /** + * Get the message value. + * + * @return the message value + */ + public String message() { + return this.message; + } + + /** + * Set the message value. + * + * @param message the message value to set + * @return the ErrorInformation object itself. + */ + public ErrorInformation withMessage(String message) { + this.message = message; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponse.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponse.java new file mode 100644 index 000000000000..fe6136a83660 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponse.java @@ -0,0 +1,43 @@ +/** + * 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.formrecognizer.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * The ErrorResponse model. + */ +public class ErrorResponse { + /** + * The error property. + */ + @JsonProperty(value = "error") + private ErrorInformation error; + + /** + * Get the error value. + * + * @return the error value + */ + public ErrorInformation error() { + return this.error; + } + + /** + * Set the error value. + * + * @param error the error value to set + * @return the ErrorResponse object itself. + */ + public ErrorResponse withError(ErrorInformation error) { + this.error = error; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponseException.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponseException.java new file mode 100644 index 000000000000..edd33e50d631 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ErrorResponseException.java @@ -0,0 +1,44 @@ +/** + * 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.formrecognizer.models; + +import com.microsoft.rest.RestException; +import okhttp3.ResponseBody; +import retrofit2.Response; + +/** + * Exception thrown for an invalid response with ErrorResponse information. + */ +public class ErrorResponseException extends RestException { + /** + * Initializes a new instance of the ErrorResponseException class. + * + * @param message the exception message or the response content if a message is not available + * @param response the HTTP response + */ + public ErrorResponseException(final String message, final Response response) { + super(message, response); + } + + /** + * Initializes a new instance of the ErrorResponseException class. + * + * @param message the exception message or the response content if a message is not available + * @param response the HTTP response + * @param body the deserialized response body + */ + public ErrorResponseException(final String message, final Response response, final ErrorResponse body) { + super(message, response, body); + } + + @Override + public ErrorResponse body() { + return (ErrorResponse) super.body(); + } +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedKeyValuePair.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedKeyValuePair.java new file mode 100644 index 000000000000..a51bd21495cc --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedKeyValuePair.java @@ -0,0 +1,71 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Representation of a key-value pair as a list + * of key and value tokens. + */ +public class ExtractedKeyValuePair { + /** + * List of tokens for the extracted key in a key-value pair. + */ + @JsonProperty(value = "key") + private List key; + + /** + * List of tokens for the extracted value in a key-value pair. + */ + @JsonProperty(value = "value") + private List value; + + /** + * Get list of tokens for the extracted key in a key-value pair. + * + * @return the key value + */ + public List key() { + return this.key; + } + + /** + * Set list of tokens for the extracted key in a key-value pair. + * + * @param key the key value to set + * @return the ExtractedKeyValuePair object itself. + */ + public ExtractedKeyValuePair withKey(List key) { + this.key = key; + return this; + } + + /** + * Get list of tokens for the extracted value in a key-value pair. + * + * @return the value value + */ + public List value() { + return this.value; + } + + /** + * Set list of tokens for the extracted value in a key-value pair. + * + * @param value the value value to set + * @return the ExtractedKeyValuePair object itself. + */ + public ExtractedKeyValuePair withValue(List value) { + this.value = value; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedPage.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedPage.java new file mode 100644 index 000000000000..f117bae1d50f --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedPage.java @@ -0,0 +1,175 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Extraction information of a single page in a + * with a document. + */ +public class ExtractedPage { + /** + * Page number. + */ + @JsonProperty(value = "number") + private Integer number; + + /** + * Height of the page (in pixels). + */ + @JsonProperty(value = "height") + private Integer height; + + /** + * Width of the page (in pixels). + */ + @JsonProperty(value = "width") + private Integer width; + + /** + * Cluster identifier. + */ + @JsonProperty(value = "clusterId") + private Integer clusterId; + + /** + * List of Key-Value pairs extracted from the page. + */ + @JsonProperty(value = "keyValuePairs") + private List keyValuePairs; + + /** + * List of Tables and their information extracted from the page. + */ + @JsonProperty(value = "tables") + private List tables; + + /** + * Get page number. + * + * @return the number value + */ + public Integer number() { + return this.number; + } + + /** + * Set page number. + * + * @param number the number value to set + * @return the ExtractedPage object itself. + */ + public ExtractedPage withNumber(Integer number) { + this.number = number; + return this; + } + + /** + * Get height of the page (in pixels). + * + * @return the height value + */ + public Integer height() { + return this.height; + } + + /** + * Set height of the page (in pixels). + * + * @param height the height value to set + * @return the ExtractedPage object itself. + */ + public ExtractedPage withHeight(Integer height) { + this.height = height; + return this; + } + + /** + * Get width of the page (in pixels). + * + * @return the width value + */ + public Integer width() { + return this.width; + } + + /** + * Set width of the page (in pixels). + * + * @param width the width value to set + * @return the ExtractedPage object itself. + */ + public ExtractedPage withWidth(Integer width) { + this.width = width; + return this; + } + + /** + * Get cluster identifier. + * + * @return the clusterId value + */ + public Integer clusterId() { + return this.clusterId; + } + + /** + * Set cluster identifier. + * + * @param clusterId the clusterId value to set + * @return the ExtractedPage object itself. + */ + public ExtractedPage withClusterId(Integer clusterId) { + this.clusterId = clusterId; + return this; + } + + /** + * Get list of Key-Value pairs extracted from the page. + * + * @return the keyValuePairs value + */ + public List keyValuePairs() { + return this.keyValuePairs; + } + + /** + * Set list of Key-Value pairs extracted from the page. + * + * @param keyValuePairs the keyValuePairs value to set + * @return the ExtractedPage object itself. + */ + public ExtractedPage withKeyValuePairs(List keyValuePairs) { + this.keyValuePairs = keyValuePairs; + return this; + } + + /** + * Get list of Tables and their information extracted from the page. + * + * @return the tables value + */ + public List tables() { + return this.tables; + } + + /** + * Set list of Tables and their information extracted from the page. + * + * @param tables the tables value to set + * @return the ExtractedPage object itself. + */ + public ExtractedPage withTables(List tables) { + this.tables = tables; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTable.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTable.java new file mode 100644 index 000000000000..d1dd9eb01b1e --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTable.java @@ -0,0 +1,71 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Extraction information about a table + * contained in a page. + */ +public class ExtractedTable { + /** + * Table identifier. + */ + @JsonProperty(value = "id") + private String id; + + /** + * List of columns contained in the table. + */ + @JsonProperty(value = "columns") + private List columns; + + /** + * Get table identifier. + * + * @return the id value + */ + public String id() { + return this.id; + } + + /** + * Set table identifier. + * + * @param id the id value to set + * @return the ExtractedTable object itself. + */ + public ExtractedTable withId(String id) { + this.id = id; + return this; + } + + /** + * Get list of columns contained in the table. + * + * @return the columns value + */ + public List columns() { + return this.columns; + } + + /** + * Set list of columns contained in the table. + * + * @param columns the columns value to set + * @return the ExtractedTable object itself. + */ + public ExtractedTable withColumns(List columns) { + this.columns = columns; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTableColumn.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTableColumn.java new file mode 100644 index 000000000000..4e14af9f89df --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedTableColumn.java @@ -0,0 +1,74 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Extraction information of a column in + * a table. + */ +public class ExtractedTableColumn { + /** + * List of extracted tokens for the column header. + */ + @JsonProperty(value = "header") + private List headerProperty; + + /** + * Extracted text for each cell of a column. Each cell + * in the column can have a list of one or more tokens. + */ + @JsonProperty(value = "entries") + private List> entries; + + /** + * Get list of extracted tokens for the column header. + * + * @return the headerProperty value + */ + public List headerProperty() { + return this.headerProperty; + } + + /** + * Set list of extracted tokens for the column header. + * + * @param headerProperty the headerProperty value to set + * @return the ExtractedTableColumn object itself. + */ + public ExtractedTableColumn withHeaderProperty(List headerProperty) { + this.headerProperty = headerProperty; + return this; + } + + /** + * Get extracted text for each cell of a column. Each cell + in the column can have a list of one or more tokens. + * + * @return the entries value + */ + public List> entries() { + return this.entries; + } + + /** + * Set extracted text for each cell of a column. Each cell + in the column can have a list of one or more tokens. + * + * @param entries the entries value to set + * @return the ExtractedTableColumn object itself. + */ + public ExtractedTableColumn withEntries(List> entries) { + this.entries = entries; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedToken.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedToken.java new file mode 100644 index 000000000000..ed920a419833 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ExtractedToken.java @@ -0,0 +1,108 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Canonical representation of single extracted text. + */ +public class ExtractedToken { + /** + * String value of the extracted text. + */ + @JsonProperty(value = "text") + private String text; + + /** + * Bounding box of the extracted text. Represents the + * location of the extracted text as a pair of + * cartesian co-ordinates. The co-ordinate pairs are arranged by + * top-left, top-right, bottom-right and bottom-left endpoints box + * with origin reference from the bottom-left of the page. + */ + @JsonProperty(value = "boundingBox") + private List boundingBox; + + /** + * A measure of accuracy of the extracted text. + */ + @JsonProperty(value = "confidence") + private Double confidence; + + /** + * Get string value of the extracted text. + * + * @return the text value + */ + public String text() { + return this.text; + } + + /** + * Set string value of the extracted text. + * + * @param text the text value to set + * @return the ExtractedToken object itself. + */ + public ExtractedToken withText(String text) { + this.text = text; + return this; + } + + /** + * Get bounding box of the extracted text. Represents the + location of the extracted text as a pair of + cartesian co-ordinates. The co-ordinate pairs are arranged by + top-left, top-right, bottom-right and bottom-left endpoints box + with origin reference from the bottom-left of the page. + * + * @return the boundingBox value + */ + public List boundingBox() { + return this.boundingBox; + } + + /** + * Set bounding box of the extracted text. Represents the + location of the extracted text as a pair of + cartesian co-ordinates. The co-ordinate pairs are arranged by + top-left, top-right, bottom-right and bottom-left endpoints box + with origin reference from the bottom-left of the page. + * + * @param boundingBox the boundingBox value to set + * @return the ExtractedToken object itself. + */ + public ExtractedToken withBoundingBox(List boundingBox) { + this.boundingBox = boundingBox; + return this; + } + + /** + * Get a measure of accuracy of the extracted text. + * + * @return the confidence value + */ + public Double confidence() { + return this.confidence; + } + + /** + * Set a measure of accuracy of the extracted text. + * + * @param confidence the confidence value to set + * @return the ExtractedToken object itself. + */ + public ExtractedToken withConfidence(Double confidence) { + this.confidence = confidence; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormDocumentReport.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormDocumentReport.java new file mode 100644 index 000000000000..12445ef60546 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormDocumentReport.java @@ -0,0 +1,123 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * The FormDocumentReport model. + */ +public class FormDocumentReport { + /** + * Reference to the data that the report is for. + */ + @JsonProperty(value = "documentName") + private String documentName; + + /** + * Total number of pages trained on. + */ + @JsonProperty(value = "pages") + private Integer pages; + + /** + * List of errors per page. + */ + @JsonProperty(value = "errors") + private List errors; + + /** + * Status of the training operation. Possible values include: 'success', + * 'partialSuccess', 'failure'. + */ + @JsonProperty(value = "status") + private String status; + + /** + * Get reference to the data that the report is for. + * + * @return the documentName value + */ + public String documentName() { + return this.documentName; + } + + /** + * Set reference to the data that the report is for. + * + * @param documentName the documentName value to set + * @return the FormDocumentReport object itself. + */ + public FormDocumentReport withDocumentName(String documentName) { + this.documentName = documentName; + return this; + } + + /** + * Get total number of pages trained on. + * + * @return the pages value + */ + public Integer pages() { + return this.pages; + } + + /** + * Set total number of pages trained on. + * + * @param pages the pages value to set + * @return the FormDocumentReport object itself. + */ + public FormDocumentReport withPages(Integer pages) { + this.pages = pages; + return this; + } + + /** + * Get list of errors per page. + * + * @return the errors value + */ + public List errors() { + return this.errors; + } + + /** + * Set list of errors per page. + * + * @param errors the errors value to set + * @return the FormDocumentReport object itself. + */ + public FormDocumentReport withErrors(List errors) { + this.errors = errors; + return this; + } + + /** + * Get status of the training operation. Possible values include: 'success', 'partialSuccess', 'failure'. + * + * @return the status value + */ + public String status() { + return this.status; + } + + /** + * Set status of the training operation. Possible values include: 'success', 'partialSuccess', 'failure'. + * + * @param status the status value to set + * @return the FormDocumentReport object itself. + */ + public FormDocumentReport withStatus(String status) { + this.status = status; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormOperationError.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormOperationError.java new file mode 100644 index 000000000000..a438db9a129f --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/FormOperationError.java @@ -0,0 +1,43 @@ +/** + * 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.formrecognizer.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Error reported during an operation. + */ +public class FormOperationError { + /** + * Message reported during the train operation. + */ + @JsonProperty(value = "errorMessage") + private String errorMessage; + + /** + * Get message reported during the train operation. + * + * @return the errorMessage value + */ + public String errorMessage() { + return this.errorMessage; + } + + /** + * Set message reported during the train operation. + * + * @param errorMessage the errorMessage value to set + * @return the FormOperationError object itself. + */ + public FormOperationError withErrorMessage(String errorMessage) { + this.errorMessage = errorMessage; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/InnerError.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/InnerError.java new file mode 100644 index 000000000000..dff5fe3b3fae --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/InnerError.java @@ -0,0 +1,43 @@ +/** + * 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.formrecognizer.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * The InnerError model. + */ +public class InnerError { + /** + * The requestId property. + */ + @JsonProperty(value = "requestId") + private String requestId; + + /** + * Get the requestId value. + * + * @return the requestId value + */ + public String requestId() { + return this.requestId; + } + + /** + * Set the requestId value. + * + * @param requestId the requestId value to set + * @return the InnerError object itself. + */ + public InnerError withRequestId(String requestId) { + this.requestId = requestId; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/KeysResult.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/KeysResult.java new file mode 100644 index 000000000000..7895ce0b6111 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/KeysResult.java @@ -0,0 +1,46 @@ +/** + * 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.formrecognizer.models; + +import java.util.Map; +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Result of an operation to get + * the keys extracted by a model. + */ +public class KeysResult { + /** + * Object mapping ClusterIds to Key lists. + */ + @JsonProperty(value = "clusters") + private Map> clusters; + + /** + * Get object mapping ClusterIds to Key lists. + * + * @return the clusters value + */ + public Map> clusters() { + return this.clusters; + } + + /** + * Set object mapping ClusterIds to Key lists. + * + * @param clusters the clusters value to set + * @return the KeysResult object itself. + */ + public KeysResult withClusters(Map> clusters) { + this.clusters = clusters; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelResult.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelResult.java new file mode 100644 index 000000000000..6ecd6ec5736b --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelResult.java @@ -0,0 +1,124 @@ +/** + * 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.formrecognizer.models; + +import java.util.UUID; +import org.joda.time.DateTime; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Result of a model status query operation. + */ +public class ModelResult { + /** + * Get or set model identifier. + */ + @JsonProperty(value = "modelId") + private UUID modelId; + + /** + * Get or set the status of model. Possible values include: 'created', + * 'ready', 'invalid'. + */ + @JsonProperty(value = "status") + private String status; + + /** + * Get or set the created date time of the model. + */ + @JsonProperty(value = "createdDateTime") + private DateTime createdDateTime; + + /** + * Get or set the model last updated datetime. + */ + @JsonProperty(value = "lastUpdatedDateTime") + private DateTime lastUpdatedDateTime; + + /** + * Get get or set model identifier. + * + * @return the modelId value + */ + public UUID modelId() { + return this.modelId; + } + + /** + * Set get or set model identifier. + * + * @param modelId the modelId value to set + * @return the ModelResult object itself. + */ + public ModelResult withModelId(UUID modelId) { + this.modelId = modelId; + return this; + } + + /** + * Get get or set the status of model. Possible values include: 'created', 'ready', 'invalid'. + * + * @return the status value + */ + public String status() { + return this.status; + } + + /** + * Set get or set the status of model. Possible values include: 'created', 'ready', 'invalid'. + * + * @param status the status value to set + * @return the ModelResult object itself. + */ + public ModelResult withStatus(String status) { + this.status = status; + return this; + } + + /** + * Get get or set the created date time of the model. + * + * @return the createdDateTime value + */ + public DateTime createdDateTime() { + return this.createdDateTime; + } + + /** + * Set get or set the created date time of the model. + * + * @param createdDateTime the createdDateTime value to set + * @return the ModelResult object itself. + */ + public ModelResult withCreatedDateTime(DateTime createdDateTime) { + this.createdDateTime = createdDateTime; + return this; + } + + /** + * Get get or set the model last updated datetime. + * + * @return the lastUpdatedDateTime value + */ + public DateTime lastUpdatedDateTime() { + return this.lastUpdatedDateTime; + } + + /** + * Set get or set the model last updated datetime. + * + * @param lastUpdatedDateTime the lastUpdatedDateTime value to set + * @return the ModelResult object itself. + */ + public ModelResult withLastUpdatedDateTime(DateTime lastUpdatedDateTime) { + this.lastUpdatedDateTime = lastUpdatedDateTime; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelsResult.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelsResult.java new file mode 100644 index 000000000000..73a94bfa8d1f --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/ModelsResult.java @@ -0,0 +1,44 @@ +/** + * 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.formrecognizer.models; + +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Result of query operation to fetch multiple models. + */ +public class ModelsResult { + /** + * Collection of models. + */ + @JsonProperty(value = "models") + private List modelsProperty; + + /** + * Get collection of models. + * + * @return the modelsProperty value + */ + public List modelsProperty() { + return this.modelsProperty; + } + + /** + * Set collection of models. + * + * @param modelsProperty the modelsProperty value to set + * @return the ModelsResult object itself. + */ + public ModelsResult withModelsProperty(List modelsProperty) { + this.modelsProperty = modelsProperty; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainRequest.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainRequest.java new file mode 100644 index 000000000000..63888b53bfd2 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainRequest.java @@ -0,0 +1,43 @@ +/** + * 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.formrecognizer.models; + +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Contract to initiate a train request. + */ +public class TrainRequest { + /** + * Get or set source path. + */ + @JsonProperty(value = "source", required = true) + private String source; + + /** + * Get get or set source path. + * + * @return the source value + */ + public String source() { + return this.source; + } + + /** + * Set get or set source path. + * + * @param source the source value to set + * @return the TrainRequest object itself. + */ + public TrainRequest withSource(String source) { + this.source = source; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainResult.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainResult.java new file mode 100644 index 000000000000..109c8b430032 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/TrainResult.java @@ -0,0 +1,100 @@ +/** + * 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.formrecognizer.models; + +import java.util.UUID; +import java.util.List; +import com.fasterxml.jackson.annotation.JsonProperty; + +/** + * Response of the Train API call. + */ +public class TrainResult { + /** + * Identifier of the model. + */ + @JsonProperty(value = "modelId") + private UUID modelId; + + /** + * List of documents used to train the model and the + * train operation error reported by each. + */ + @JsonProperty(value = "trainingDocuments") + private List trainingDocuments; + + /** + * Errors returned during the training operation. + */ + @JsonProperty(value = "errors") + private List errors; + + /** + * Get identifier of the model. + * + * @return the modelId value + */ + public UUID modelId() { + return this.modelId; + } + + /** + * Set identifier of the model. + * + * @param modelId the modelId value to set + * @return the TrainResult object itself. + */ + public TrainResult withModelId(UUID modelId) { + this.modelId = modelId; + return this; + } + + /** + * Get list of documents used to train the model and the + train operation error reported by each. + * + * @return the trainingDocuments value + */ + public List trainingDocuments() { + return this.trainingDocuments; + } + + /** + * Set list of documents used to train the model and the + train operation error reported by each. + * + * @param trainingDocuments the trainingDocuments value to set + * @return the TrainResult object itself. + */ + public TrainResult withTrainingDocuments(List trainingDocuments) { + this.trainingDocuments = trainingDocuments; + return this; + } + + /** + * Get errors returned during the training operation. + * + * @return the errors value + */ + public List errors() { + return this.errors; + } + + /** + * Set errors returned during the training operation. + * + * @param errors the errors value to set + * @return the TrainResult object itself. + */ + public TrainResult withErrors(List errors) { + this.errors = errors; + return this; + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java new file mode 100644 index 000000000000..a1fc906534ed --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java @@ -0,0 +1,11 @@ +// 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. + +/** + * This package contains the models classes for CognitiveServiceFormRecognizerAPIV1Preview. + * Extracts information from forms and images into structured data based on a model created by a set of representative training forms. + */ +package com.microsoft.azure.cognitiveservices.formrecognizer.models; diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java new file mode 100644 index 000000000000..836f65091538 --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java @@ -0,0 +1,11 @@ +// 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. + +/** + * This package contains the classes for CognitiveServiceFormRecognizerAPIV1Preview. + * Extracts information from forms and images into structured data based on a model created by a set of representative training forms. + */ +package com.microsoft.azure.cognitiveservices.formrecognizer; From acd1077dd69b6f39dfe8250832be766a798a501b Mon Sep 17 00:00:00 2001 From: Azure SDK for Python bot Date: Thu, 2 May 2019 17:41:44 -0700 Subject: [PATCH 2/4] Generated from af8009ba5c5f718bdf18e19407b076602dc82999 (#3517) Update title to be used for SDK code generation --- .../formrecognizer/FormRecognizerClient.java | 430 +++++++++ .../FormRecognizerClientImpl.java | 829 ++++++++++++++++++ .../implementation/package-info.java | 2 +- .../formrecognizer/models/package-info.java | 2 +- .../formrecognizer/package-info.java | 2 +- 5 files changed, 1262 insertions(+), 3 deletions(-) create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java create mode 100644 cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java new file mode 100644 index 000000000000..17d11e71aeec --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java @@ -0,0 +1,430 @@ +/** + * 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.formrecognizer; + +import com.microsoft.azure.AzureClient; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.AnalyzeResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ErrorResponseException; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.KeysResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelsResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.TrainResult; +import com.microsoft.rest.RestClient; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import rx.Observable; + +/** + * The interface for FormRecognizerClient class. + */ +public interface FormRecognizerClient { + /** + * Gets the REST client. + * + * @return the {@link RestClient} object. + */ + RestClient restClient(); + + /** + * Gets the {@link AzureClient} used for long running operations. + * @return the azure client; + */ + AzureClient getAzureClient(); + + /** + * Gets the User-Agent header for the client. + * + * @return the user agent string. + */ + String userAgent(); + + /** + * Gets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).. + * + * @return the endpoint value. + */ + String endpoint(); + + /** + * Sets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com).. + * + * @param endpoint the endpoint value. + * @return the service client itself + */ + FormRecognizerClient withEndpoint(String endpoint); + + /** + * Gets The preferred language for the response.. + * + * @return the acceptLanguage value. + */ + String acceptLanguage(); + + /** + * Sets The preferred language for the response.. + * + * @param acceptLanguage the acceptLanguage value. + * @return the service client itself + */ + FormRecognizerClient withAcceptLanguage(String acceptLanguage); + + /** + * Gets The retry timeout in seconds for Long Running Operations. Default value is 30.. + * + * @return the longRunningOperationRetryTimeout value. + */ + int longRunningOperationRetryTimeout(); + + /** + * Sets The retry timeout in seconds for Long Running Operations. Default value is 30.. + * + * @param longRunningOperationRetryTimeout the longRunningOperationRetryTimeout value. + * @return the service client itself + */ + FormRecognizerClient withLongRunningOperationRetryTimeout(int longRunningOperationRetryTimeout); + + /** + * Gets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true.. + * + * @return the generateClientRequestId value. + */ + boolean generateClientRequestId(); + + /** + * Sets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true.. + * + * @param generateClientRequestId the generateClientRequestId value. + * @return the service client itself + */ + FormRecognizerClient withGenerateClientRequestId(boolean generateClientRequestId); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the TrainResult object if successful. + */ + TrainResult trainCustomModel(String source); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture trainCustomModelAsync(String source, final ServiceCallback serviceCallback); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + Observable trainCustomModelAsync(String source); + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + Observable> trainCustomModelWithServiceResponseAsync(String source); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the KeysResult object if successful. + */ + KeysResult getExtractedKeys(UUID id); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getExtractedKeysAsync(UUID id, final ServiceCallback serviceCallback); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + Observable getExtractedKeysAsync(UUID id); + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + Observable> getExtractedKeysWithServiceResponseAsync(UUID id); + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelsResult object if successful. + */ + ModelsResult getCustomModels(); + + /** + * Get Models. + * Get information about all trained models. + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getCustomModelsAsync(final ServiceCallback serviceCallback); + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + Observable getCustomModelsAsync(); + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + Observable> getCustomModelsWithServiceResponseAsync(); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelResult object if successful. + */ + ModelResult getCustomModel(UUID id); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture getCustomModelAsync(UUID id, final ServiceCallback serviceCallback); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + Observable getCustomModelAsync(UUID id); + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + Observable> getCustomModelWithServiceResponseAsync(UUID id); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + */ + void deleteCustomModel(UUID id); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture deleteCustomModelAsync(UUID id, final ServiceCallback serviceCallback); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable deleteCustomModelAsync(UUID id); + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + Observable> deleteCustomModelWithServiceResponseAsync(UUID id); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, final ServiceCallback serviceCallback); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream); + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream, List keys); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys, final ServiceCallback serviceCallback); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys); + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream, List keys); + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java new file mode 100644 index 000000000000..e8cbab09252a --- /dev/null +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java @@ -0,0 +1,829 @@ +/** + * 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.formrecognizer.implementation; + +import com.google.common.base.Joiner; +import com.google.common.reflect.TypeToken; +import com.microsoft.azure.AzureClient; +import com.microsoft.azure.AzureServiceClient; +import com.microsoft.azure.cognitiveservices.formrecognizer.FormRecognizerClient; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.AnalyzeResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ErrorResponseException; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.KeysResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.ModelsResult; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.TrainRequest; +import com.microsoft.azure.cognitiveservices.formrecognizer.models.TrainResult; +import com.microsoft.rest.CollectionFormat; +import com.microsoft.rest.credentials.ServiceClientCredentials; +import com.microsoft.rest.RestClient; +import com.microsoft.rest.ServiceCallback; +import com.microsoft.rest.ServiceFuture; +import com.microsoft.rest.ServiceResponse; +import com.microsoft.rest.Validator; +import java.io.InputStream; +import java.io.IOException; +import java.util.List; +import java.util.UUID; +import okhttp3.ResponseBody; +import retrofit2.http.Body; +import retrofit2.http.GET; +import retrofit2.http.Header; +import retrofit2.http.Headers; +import retrofit2.http.HTTP; +import retrofit2.http.Multipart; +import retrofit2.http.Part; +import retrofit2.http.Path; +import retrofit2.http.POST; +import retrofit2.http.Query; +import retrofit2.Response; +import rx.functions.Func1; +import rx.Observable; + +/** + * Initializes a new instance of the FormRecognizerClientImpl class. + */ +public class FormRecognizerClientImpl extends AzureServiceClient implements FormRecognizerClient { + /** The Retrofit service to perform REST calls. */ + private FormRecognizerClientService service; + /** the {@link AzureClient} used for long running operations. */ + private AzureClient azureClient; + + /** + * Gets the {@link AzureClient} used for long running operations. + * @return the azure client; + */ + public AzureClient getAzureClient() { + return this.azureClient; + } + + /** Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com). */ + private String endpoint; + + /** + * Gets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com). + * + * @return the endpoint value. + */ + public String endpoint() { + return this.endpoint; + } + + /** + * Sets Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus2.api.cognitive.microsoft.com). + * + * @param endpoint the endpoint value. + * @return the service client itself + */ + public FormRecognizerClientImpl withEndpoint(String endpoint) { + this.endpoint = endpoint; + return this; + } + + /** The preferred language for the response. */ + private String acceptLanguage; + + /** + * Gets The preferred language for the response. + * + * @return the acceptLanguage value. + */ + public String acceptLanguage() { + return this.acceptLanguage; + } + + /** + * Sets The preferred language for the response. + * + * @param acceptLanguage the acceptLanguage value. + * @return the service client itself + */ + public FormRecognizerClientImpl withAcceptLanguage(String acceptLanguage) { + this.acceptLanguage = acceptLanguage; + return this; + } + + /** The retry timeout in seconds for Long Running Operations. Default value is 30. */ + private int longRunningOperationRetryTimeout; + + /** + * Gets The retry timeout in seconds for Long Running Operations. Default value is 30. + * + * @return the longRunningOperationRetryTimeout value. + */ + public int longRunningOperationRetryTimeout() { + return this.longRunningOperationRetryTimeout; + } + + /** + * Sets The retry timeout in seconds for Long Running Operations. Default value is 30. + * + * @param longRunningOperationRetryTimeout the longRunningOperationRetryTimeout value. + * @return the service client itself + */ + public FormRecognizerClientImpl withLongRunningOperationRetryTimeout(int longRunningOperationRetryTimeout) { + this.longRunningOperationRetryTimeout = longRunningOperationRetryTimeout; + return this; + } + + /** Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. */ + private boolean generateClientRequestId; + + /** + * Gets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. + * + * @return the generateClientRequestId value. + */ + public boolean generateClientRequestId() { + return this.generateClientRequestId; + } + + /** + * Sets Whether a unique x-ms-client-request-id should be generated. When set to true a unique x-ms-client-request-id value is generated and included in each request. Default is true. + * + * @param generateClientRequestId the generateClientRequestId value. + * @return the service client itself + */ + public FormRecognizerClientImpl withGenerateClientRequestId(boolean generateClientRequestId) { + this.generateClientRequestId = generateClientRequestId; + return this; + } + + /** + * Initializes an instance of FormRecognizerClient client. + * + * @param credentials the management credentials for Azure + */ + public FormRecognizerClientImpl(ServiceClientCredentials credentials) { + this("https://{Endpoint}/formrecognizer/v1.0-preview", credentials); + } + + /** + * Initializes an instance of FormRecognizerClient client. + * + * @param baseUrl the base URL of the host + * @param credentials the management credentials for Azure + */ + private FormRecognizerClientImpl(String baseUrl, ServiceClientCredentials credentials) { + super(baseUrl, credentials); + initialize(); + } + + /** + * Initializes an instance of FormRecognizerClient client. + * + * @param restClient the REST client to connect to Azure. + */ + public FormRecognizerClientImpl(RestClient restClient) { + super(restClient); + initialize(); + } + + protected void initialize() { + this.acceptLanguage = "en-US"; + this.longRunningOperationRetryTimeout = 30; + this.generateClientRequestId = true; + this.azureClient = new AzureClient(this); + initializeService(); + } + + /** + * Gets the User-Agent header for the client. + * + * @return the user agent string. + */ + @Override + public String userAgent() { + return String.format("%s (%s, %s)", super.userAgent(), "FormRecognizerClient", "v1.0-preview"); + } + + private void initializeService() { + service = restClient().retrofit().create(FormRecognizerClientService.class); + } + + /** + * The interface defining all the services for FormRecognizerClient to be + * used by Retrofit to perform actually REST calls. + */ + interface FormRecognizerClientService { + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.FormRecognizerClient trainCustomModel" }) + @POST("custom/train") + Observable> trainCustomModel(@Header("accept-language") String acceptLanguage, @Body TrainRequest trainRequest, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.FormRecognizerClient getExtractedKeys" }) + @GET("custom/models/{id}/keys") + Observable> getExtractedKeys(@Path("id") UUID id, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.FormRecognizerClient getCustomModels" }) + @GET("custom/models") + Observable> getCustomModels(@Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.FormRecognizerClient getCustomModel" }) + @GET("custom/models/{id}") + Observable> getCustomModel(@Path("id") UUID id, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Headers({ "Content-Type: application/json; charset=utf-8", "x-ms-logging-context: com.microsoft.azure.cognitiveservices.formrecognizer.FormRecognizerClient deleteCustomModel" }) + @HTTP(path = "custom/models/{id}", method = "DELETE", hasBody = true) + Observable> deleteCustomModel(@Path("id") UUID id, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + @Multipart + @POST("custom/models/{id}/analyze") + Observable> analyzeWithCustomModel(@Path("id") UUID id, @Query("keys") String keys, @Part("form_stream") RequestBody formStream, @Header("accept-language") String acceptLanguage, @Header("x-ms-parameterized-host") String parameterizedHost, @Header("User-Agent") String userAgent); + + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the TrainResult object if successful. + */ + public TrainResult trainCustomModel(String source) { + return trainCustomModelWithServiceResponseAsync(source).toBlocking().single().body(); + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture trainCustomModelAsync(String source, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(trainCustomModelWithServiceResponseAsync(source), serviceCallback); + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + public Observable trainCustomModelAsync(String source) { + return trainCustomModelWithServiceResponseAsync(source).map(new Func1, TrainResult>() { + @Override + public TrainResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Train Model. + * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other content is ignored when training a model. + * + * @param source Get or set source path. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the TrainResult object + */ + public Observable> trainCustomModelWithServiceResponseAsync(String source) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (source == null) { + throw new IllegalArgumentException("Parameter source is required and cannot be null."); + } + TrainRequest trainRequest = new TrainRequest(); + trainRequest.withSource(source); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.trainCustomModel(this.acceptLanguage(), trainRequest, parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = trainCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse trainCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the KeysResult object if successful. + */ + public KeysResult getExtractedKeys(UUID id) { + return getExtractedKeysWithServiceResponseAsync(id).toBlocking().single().body(); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getExtractedKeysAsync(UUID id, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getExtractedKeysWithServiceResponseAsync(id), serviceCallback); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + public Observable getExtractedKeysAsync(UUID id) { + return getExtractedKeysWithServiceResponseAsync(id).map(new Func1, KeysResult>() { + @Override + public KeysResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Get Keys. + * Use the API to retrieve the keys that were + extracted by the specified model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the KeysResult object + */ + public Observable> getExtractedKeysWithServiceResponseAsync(UUID id) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.getExtractedKeys(id, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getExtractedKeysDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getExtractedKeysDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelsResult object if successful. + */ + public ModelsResult getCustomModels() { + return getCustomModelsWithServiceResponseAsync().toBlocking().single().body(); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getCustomModelsAsync(final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getCustomModelsWithServiceResponseAsync(), serviceCallback); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + public Observable getCustomModelsAsync() { + return getCustomModelsWithServiceResponseAsync().map(new Func1, ModelsResult>() { + @Override + public ModelsResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Get Models. + * Get information about all trained models. + * + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelsResult object + */ + public Observable> getCustomModelsWithServiceResponseAsync() { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.getCustomModels(this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getCustomModelsDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getCustomModelsDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the ModelResult object if successful. + */ + public ModelResult getCustomModel(UUID id) { + return getCustomModelWithServiceResponseAsync(id).toBlocking().single().body(); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture getCustomModelAsync(UUID id, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(getCustomModelWithServiceResponseAsync(id), serviceCallback); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + public Observable getCustomModelAsync(UUID id) { + return getCustomModelWithServiceResponseAsync(id).map(new Func1, ModelResult>() { + @Override + public ModelResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Get Model. + * Get information about a model. + * + * @param id Model identifier. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the ModelResult object + */ + public Observable> getCustomModelWithServiceResponseAsync(UUID id) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.getCustomModel(id, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = getCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse getCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + */ + public void deleteCustomModel(UUID id) { + deleteCustomModelWithServiceResponseAsync(id).toBlocking().single().body(); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture deleteCustomModelAsync(UUID id, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(deleteCustomModelWithServiceResponseAsync(id), serviceCallback); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable deleteCustomModelAsync(UUID id) { + return deleteCustomModelWithServiceResponseAsync(id).map(new Func1, Void>() { + @Override + public Void call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Delete Model. + * Delete model artifacts. + * + * @param id The identifier of the model to delete. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceResponse} object if successful. + */ + public Observable> deleteCustomModelWithServiceResponseAsync(UUID id) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + return service.deleteCustomModel(id, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = deleteCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse deleteCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(204, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + public AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream).toBlocking().single().body(); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(analyzeWithCustomModelWithServiceResponseAsync(id, formStream), serviceCallback); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream).map(new Func1, AnalyzeResult>() { + @Override + public AnalyzeResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + if (formStream == null) { + throw new IllegalArgumentException("Parameter formStream is required and cannot be null."); + } + final List keys = null; + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + String keysConverted = this.serializerAdapter().serializeList(keys, CollectionFormat.CSV);RequestBody formStreamConverted = RequestBody.create(MediaType.parse("multipart/form-data"), formStream); + return service.analyzeWithCustomModel(id, keysConverted, formStreamConverted, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = analyzeWithCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @throws ErrorResponseException thrown if the request is rejected by server + * @throws RuntimeException all other wrapped checked exceptions if the request fails to be sent + * @return the AnalyzeResult object if successful. + */ + public AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream, List keys) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream, keys).toBlocking().single().body(); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @param serviceCallback the async ServiceCallback to handle successful and failed responses. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the {@link ServiceFuture} object + */ + public ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys, final ServiceCallback serviceCallback) { + return ServiceFuture.fromResponse(analyzeWithCustomModelWithServiceResponseAsync(id, formStream, keys), serviceCallback); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable analyzeWithCustomModelAsync(UUID id, byte[] formStream, List keys) { + return analyzeWithCustomModelWithServiceResponseAsync(id, formStream, keys).map(new Func1, AnalyzeResult>() { + @Override + public AnalyzeResult call(ServiceResponse response) { + return response.body(); + } + }); + } + + /** + * Analyze Form. + * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * + * @param id Model Identifier to analyze the document with. + * @param formStream A pdf document or image (jpg,png) file to analyze. + * @param keys An optional list of known keys to extract the values for. + * @throws IllegalArgumentException thrown if parameters fail the validation + * @return the observable to the AnalyzeResult object + */ + public Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream, List keys) { + if (this.endpoint() == null) { + throw new IllegalArgumentException("Parameter this.endpoint() is required and cannot be null."); + } + if (id == null) { + throw new IllegalArgumentException("Parameter id is required and cannot be null."); + } + if (formStream == null) { + throw new IllegalArgumentException("Parameter formStream is required and cannot be null."); + } + Validator.validate(keys); + String parameterizedHost = Joiner.on(", ").join("{Endpoint}", this.endpoint()); + String keysConverted = this.serializerAdapter().serializeList(keys, CollectionFormat.CSV);RequestBody formStreamConverted = RequestBody.create(MediaType.parse("multipart/form-data"), formStream); + return service.analyzeWithCustomModel(id, keysConverted, formStreamConverted, this.acceptLanguage(), parameterizedHost, this.userAgent()) + .flatMap(new Func1, Observable>>() { + @Override + public Observable> call(Response response) { + try { + ServiceResponse clientResponse = analyzeWithCustomModelDelegate(response); + return Observable.just(clientResponse); + } catch (Throwable t) { + return Observable.error(t); + } + } + }); + } + + private ServiceResponse analyzeWithCustomModelDelegate(Response response) throws ErrorResponseException, IOException, IllegalArgumentException { + return this.restClient().responseBuilderFactory().newInstance(this.serializerAdapter()) + .register(200, new TypeToken() { }.getType()) + .registerError(ErrorResponseException.class) + .build(response); + } + +} diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java index 56bcefa64381..21d56e89255d 100644 --- a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/package-info.java @@ -5,7 +5,7 @@ // Code generated by Microsoft (R) AutoRest Code Generator. /** - * This package contains the implementation classes for CognitiveServiceFormRecognizerAPIV1Preview. + * This package contains the implementation classes for FormRecognizerClient. * Extracts information from forms and images into structured data based on a model created by a set of representative training forms. */ package com.microsoft.azure.cognitiveservices.formrecognizer.implementation; diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java index a1fc906534ed..15203a81a7b6 100644 --- a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/models/package-info.java @@ -5,7 +5,7 @@ // Code generated by Microsoft (R) AutoRest Code Generator. /** - * This package contains the models classes for CognitiveServiceFormRecognizerAPIV1Preview. + * This package contains the models classes for FormRecognizerClient. * Extracts information from forms and images into structured data based on a model created by a set of representative training forms. */ package com.microsoft.azure.cognitiveservices.formrecognizer.models; diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java index 836f65091538..da1bcbdb932d 100644 --- a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/package-info.java @@ -5,7 +5,7 @@ // Code generated by Microsoft (R) AutoRest Code Generator. /** - * This package contains the classes for CognitiveServiceFormRecognizerAPIV1Preview. + * This package contains the classes for FormRecognizerClient. * Extracts information from forms and images into structured data based on a model created by a set of representative training forms. */ package com.microsoft.azure.cognitiveservices.formrecognizer; From 23601aa58640fc94f89771498cc2ed8ddcbbaea5 Mon Sep 17 00:00:00 2001 From: Azure SDK for Python bot Date: Tue, 7 May 2019 17:01:31 -0700 Subject: [PATCH 3/4] Generated from e405bd9eb8d4b0660db9fa686a9ad6b1f41266a6 (#3587) Fix version in form recognizer --- .../formrecognizer/implementation/FormRecognizerClientImpl.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java index e8cbab09252a..cb92ac2d54e5 100644 --- a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java @@ -200,7 +200,7 @@ protected void initialize() { */ @Override public String userAgent() { - return String.format("%s (%s, %s)", super.userAgent(), "FormRecognizerClient", "v1.0-preview"); + return String.format("%s (%s, %s)", super.userAgent(), "FormRecognizerClient", "1.0-preview"); } private void initializeService() { From 4eb5114a4f46168d3d510aef98273b1da97bfe58 Mon Sep 17 00:00:00 2001 From: Azure SDK for Python bot Date: Wed, 15 May 2019 10:17:29 -0700 Subject: [PATCH 4/4] Generated from e8cce48ae660d330c7073a6968d8eecfd53976f5 (#3647) Update help text. --- .../formrecognizer/FormRecognizerClient.java | 64 +++++++++---------- .../FormRecognizerClientImpl.java | 64 +++++++++---------- 2 files changed, 64 insertions(+), 64 deletions(-) diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java index 17d11e71aeec..cccb750d9455 100644 --- a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/FormRecognizerClient.java @@ -110,9 +110,9 @@ public interface FormRecognizerClient { /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -124,9 +124,9 @@ public interface FormRecognizerClient { /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. @@ -137,9 +137,9 @@ public interface FormRecognizerClient { /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -149,9 +149,9 @@ public interface FormRecognizerClient { /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -161,8 +161,8 @@ public interface FormRecognizerClient { /** * Get Keys. - * Use the API to retrieve the keys that were - extracted by the specified model. + * Retrieve the keys that were + extracted during the training of the specified model. * * @param id Model identifier. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -174,8 +174,8 @@ public interface FormRecognizerClient { /** * Get Keys. - * Use the API to retrieve the keys that were - extracted by the specified model. + * Retrieve the keys that were + extracted during the training of the specified model. * * @param id Model identifier. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. @@ -186,8 +186,8 @@ public interface FormRecognizerClient { /** * Get Keys. - * Use the API to retrieve the keys that were - extracted by the specified model. + * Retrieve the keys that were + extracted during the training of the specified model. * * @param id Model identifier. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -197,8 +197,8 @@ public interface FormRecognizerClient { /** * Get Keys. - * Use the API to retrieve the keys that were - extracted by the specified model. + * Retrieve the keys that were + extracted during the training of the specified model. * * @param id Model identifier. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -208,7 +208,7 @@ public interface FormRecognizerClient { /** * Get Models. - * Get information about all trained models. + * Get information about all trained custom models. * * @throws IllegalArgumentException thrown if parameters fail the validation * @throws ErrorResponseException thrown if the request is rejected by server @@ -219,7 +219,7 @@ public interface FormRecognizerClient { /** * Get Models. - * Get information about all trained models. + * Get information about all trained custom models. * * @param serviceCallback the async ServiceCallback to handle successful and failed responses. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -229,7 +229,7 @@ public interface FormRecognizerClient { /** * Get Models. - * Get information about all trained models. + * Get information about all trained custom models. * * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the ModelsResult object @@ -238,7 +238,7 @@ public interface FormRecognizerClient { /** * Get Models. - * Get information about all trained models. + * Get information about all trained custom models. * * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the ModelsResult object @@ -332,7 +332,7 @@ public interface FormRecognizerClient { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -345,7 +345,7 @@ public interface FormRecognizerClient { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -357,7 +357,7 @@ public interface FormRecognizerClient { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -368,7 +368,7 @@ public interface FormRecognizerClient { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -378,7 +378,7 @@ public interface FormRecognizerClient { Observable> analyzeWithCustomModelWithServiceResponseAsync(UUID id, byte[] formStream); /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -392,7 +392,7 @@ public interface FormRecognizerClient { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -405,7 +405,7 @@ public interface FormRecognizerClient { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -417,7 +417,7 @@ public interface FormRecognizerClient { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. diff --git a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java index cb92ac2d54e5..3cb2c8519731 100644 --- a/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java +++ b/cognitiveservices/data-plane/vision/formrecognizer/src/main/java/com/microsoft/azure/cognitiveservices/formrecognizer/implementation/FormRecognizerClientImpl.java @@ -240,9 +240,9 @@ interface FormRecognizerClientService { /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -256,9 +256,9 @@ public TrainResult trainCustomModel(String source) { /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @param serviceCallback the async ServiceCallback to handle successful and failed responses. @@ -271,9 +271,9 @@ public ServiceFuture trainCustomModelAsync(String source, final Ser /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -290,9 +290,9 @@ public TrainResult call(ServiceResponse response) { /** * Train Model. - * The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration - setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained are expected to be under the source. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." - Other content is ignored when training a model. + * Create and train a custom model. The train request must include a source parameter that is either an externally accessible Azure Storage blob container Uri (preferably a Shared Access Signature Uri) or valid path to a data folder in a locally mounted drive. When local paths are specified, they must follow the Linux/Unix path format and be an absolute path rooted to the input mount configuration + setting value e.g., if '{Mounts:Input}' configuration setting value is '/input' then a valid source path would be '/input/contosodataset'. All data to be trained is expected to be directly under the source folder. Subfolders are not supported. Models are trained using documents that are of the following content type - 'application/pdf', 'image/jpeg' and 'image/png'." + Other type of content is ignored. * * @param source Get or set source path. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -331,8 +331,8 @@ private ServiceResponse trainCustomModelDelegate(Response getExtractedKeysAsync(UUID id, final ServiceCal /** * Get Keys. - * Use the API to retrieve the keys that were - extracted by the specified model. + * Retrieve the keys that were + extracted during the training of the specified model. * * @param id Model identifier. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -378,8 +378,8 @@ public KeysResult call(ServiceResponse response) { /** * Get Keys. - * Use the API to retrieve the keys that were - extracted by the specified model. + * Retrieve the keys that were + extracted during the training of the specified model. * * @param id Model identifier. * @throws IllegalArgumentException thrown if parameters fail the validation @@ -416,7 +416,7 @@ private ServiceResponse getExtractedKeysDelegate(Response getCustomModelsAsync(final ServiceCallback response) { /** * Get Models. - * Get information about all trained models. + * Get information about all trained custom models. * * @throws IllegalArgumentException thrown if parameters fail the validation * @return the observable to the ModelsResult object @@ -651,7 +651,7 @@ private ServiceResponse deleteCustomModelDelegate(Response r /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -666,7 +666,7 @@ public AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream) { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -680,7 +680,7 @@ public ServiceFuture analyzeWithCustomModelAsync(UUID id, byte[] /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -698,7 +698,7 @@ public AnalyzeResult call(ServiceResponse response) { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -734,7 +734,7 @@ public Observable> call(Response re /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -750,7 +750,7 @@ public AnalyzeResult analyzeWithCustomModel(UUID id, byte[] formStream, List analyzeWithCustomModelAsync(UUID id, byte[] /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze. @@ -784,7 +784,7 @@ public AnalyzeResult call(ServiceResponse response) { /** * Analyze Form. - * The document to analyze must be of a supported content type - 'application/pdf', 'image/jpeg' or 'image/png'. The response contains not just the extracted information of the analyzed form but also information about content that was not extracted along with a reason. + * Extract key-value pairs from a given document. The input document must be of one of the supported content types - 'application/pdf', 'image/jpeg' or 'image/png'. A success response is returned in JSON. * * @param id Model Identifier to analyze the document with. * @param formStream A pdf document or image (jpg,png) file to analyze.