Add implementation for relationship APIs (Azure#14527)

* feat(adt): Add implementation for relationship APIs

sdk/digitaltwins/azure-digitaltwins-core/src/main/java/com/azure/digitaltwins/core/DigitalTwinsClient.java

@@ -7,19 +7,17 @@
 import com.azure.core.annotation.ServiceClient;
 import com.azure.core.annotation.ServiceMethod;
 import com.azure.core.http.HttpPipeline;
-import com.azure.core.http.rest.*;
+import com.azure.core.http.rest.PagedFlux;
+import com.azure.core.http.rest.PagedIterable;
+import com.azure.core.http.rest.Response;
 import com.azure.core.util.Context;
-import com.azure.digitaltwins.core.implementation.models.DigitalTwinModelsListOptions;
+import com.azure.digitaltwins.core.implementation.models.IncomingRelationship;
 import com.azure.digitaltwins.core.models.ModelData;
+import com.azure.digitaltwins.core.util.DigitalTwinsResponse;
 import com.azure.digitaltwins.core.util.ListModelOptions;
-import com.fasterxml.jackson.core.JsonProcessingException;
-import reactor.core.publisher.Mono;
 
-import java.util.ArrayList;
 import java.util.List;
 
-import static com.azure.core.util.FluxUtil.withContext;
-
 /**
  * This class provides a client for interacting synchronously with an Azure Digital Twins instance.
  *
@@ -61,21 +59,181 @@ public DigitalTwinsServiceVersion getServiceVersion() {
         return this.digitalTwinsAsyncClient.getServiceVersion();
     }
 
-    // TODO These are temporary implementations for sample purposes. This should be spruced up/replaced once this API is actually designed.
+    /**
+     * Creates a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to be created.
+     * @param relationship The application/json relationship to be created.
+     * @return The application/json relationship created.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public String createRelationship(String digitalTwinId, String relationshipId, String relationship) {
+        return createRelationshipWithResponse(digitalTwinId, relationshipId, relationship, Context.NONE).getValue();
+    }
+
     /**
      * Creates a relationship on a digital twin.
      *
      * @param digitalTwinId The Id of the source digital twin.
      * @param relationshipId The Id of the relationship to be created.
      * @param relationship The application/json relationship to be created.
      * @param context Additional context that is passed through the Http pipeline during the service call.
-     * @return A REST response containing the application/json relationship created.
+     * @return The Http response containing the application/json relationship created.
      */
     @ServiceMethod(returns = ReturnType.SINGLE)
-    public Response<String> createRelationshipWithResponse(String digitalTwinId, String relationshipId, String relationship, Context context) {
+    public DigitalTwinsResponse<String> createRelationshipWithResponse(String digitalTwinId, String relationshipId, String relationship, Context context) {
         return digitalTwinsAsyncClient.createRelationshipWithResponse(digitalTwinId, relationshipId, relationship, context).block();
     }
 
+    /**
+     * Creates a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to be created.
+     * @param relationship The relationship to be created.
+     * @param clazz The model class to convert the relationship to.
+     * @param <T> The generic type to convert the relationship to.
+     * @return The relationship created.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public <T> T createRelationship(String digitalTwinId, String relationshipId, Object relationship, Class<T> clazz) {
+        return createRelationshipWithResponse(digitalTwinId, relationshipId, relationship, clazz, Context.NONE).getValue();
+    }
+
+    /**
+     * Creates a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to be created.
+     * @param relationship The relationship to be created.
+     * @param clazz The model class to convert the relationship to.
+     * @param <T> The generic type to convert the relationship to.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return The Http response containing the relationship created.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public <T> DigitalTwinsResponse<T> createRelationshipWithResponse(String digitalTwinId, String relationshipId, Object relationship, Class<T> clazz, Context context) {
+        return digitalTwinsAsyncClient.createRelationshipWithResponse(digitalTwinId, relationshipId, relationship, clazz, context).block();
+    }
+
+    /**
+     * Gets a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to retrieve.
+     * @return The application/json relationship corresponding to the provided relationshipId.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public String getRelationship(String digitalTwinId, String relationshipId) {
+        return getRelationshipWithResponse(digitalTwinId, relationshipId, Context.NONE).getValue();
+    }
+
+    /**
+     * Gets a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to retrieve.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return The Http response containing the application/json relationship corresponding to the provided relationshipId.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public DigitalTwinsResponse<String> getRelationshipWithResponse(String digitalTwinId, String relationshipId, Context context) {
+        return digitalTwinsAsyncClient.getRelationshipWithResponse(digitalTwinId, relationshipId, context).block();
+    }
+
+    /**
+     * Gets a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to retrieve.
+     * @param clazz The model class to convert the relationship to.
+     * @param <T> The generic type to convert the relationship to.
+     * @return The relationship corresponding to the provided relationshipId.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public <T> T getRelationship(String digitalTwinId, String relationshipId, Class<T> clazz) {
+        return getRelationshipWithResponse(digitalTwinId, relationshipId, clazz, Context.NONE).getValue();
+    }
+
+    /**
+     * Gets a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to retrieve.
+     * @param clazz The model class to convert the relationship to.
+     * @param <T> The generic type to convert the relationship to.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return The Http response containing the relationship corresponding to the provided relationshipId.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public <T> DigitalTwinsResponse<T> getRelationshipWithResponse(String digitalTwinId, String relationshipId, Class<T> clazz, Context context) {
+        return digitalTwinsAsyncClient.getRelationshipWithResponse(digitalTwinId, relationshipId, clazz, context).block();
+    }
+
+    /**
+     * Updates the properties of a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to be updated.
+     * @param relationshipUpdateOperations The list of application/json-patch+json operations to be performed on the specified digital twin's relationship.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public void updateRelationship(String digitalTwinId, String relationshipId, List<Object> relationshipUpdateOperations) {
+        updateRelationshipWithResponse(digitalTwinId, relationshipId, relationshipUpdateOperations, new RequestOptions(), Context.NONE);
+    }
+
+    /**
+     * Updates the properties of a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to be updated.
+     * @param relationshipUpdateOperations The list of application/json-patch+json operations to be performed on the specified digital twin's relationship.
+     * @param options The optional settings for this request.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return The Http response.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public DigitalTwinsResponse<Void> updateRelationshipWithResponse(String digitalTwinId, String relationshipId, List<Object> relationshipUpdateOperations, RequestOptions options, Context context) {
+        return digitalTwinsAsyncClient.updateRelationshipWithResponse(digitalTwinId, relationshipId, relationshipUpdateOperations, options, context).block();
+    }
+
+    /**
+     * Deletes a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to delete.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public void deleteRelationship(String digitalTwinId, String relationshipId) {
+        deleteRelationshipWithResponse(digitalTwinId, relationshipId, new RequestOptions(), Context.NONE);
+    }
+
+    /**
+     * Deletes a relationship on a digital twin.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipId The Id of the relationship to delete.
+     * @param options The optional settings for this request.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return The Http response.
+     */
+    @ServiceMethod(returns = ReturnType.SINGLE)
+    public Response<Void> deleteRelationshipWithResponse(String digitalTwinId, String relationshipId, RequestOptions options, Context context) {
+        return digitalTwinsAsyncClient.deleteRelationshipWithResponse(digitalTwinId, relationshipId, options, context).block();
+    }
+
+    /**
+     * Gets all the relationships on a digital twin by iterating through a collection.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @return A {@link PagedIterable} of application/json relationships belonging to the specified digital twin and the http response.
+     */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
+    public PagedIterable<String> listRelationships(String digitalTwinId) {
+        return listRelationships(digitalTwinId, null, Context.NONE);
+    }
+
     /**
      * Gets all the relationships on a digital twin filtered by the relationship name, by iterating through a collection.
      *
@@ -89,6 +247,46 @@ public PagedIterable<String> listRelationships(String digitalTwinId, String rela
         return new PagedIterable<>(digitalTwinsAsyncClient.listRelationships(digitalTwinId, relationshipName, context));
     }
 
+    /**
+     * Gets all the relationships on a digital twin by iterating through a collection.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param clazz The model class to convert the relationship to. Since a digital twin might have relationships conforming to different models, it is advisable to convert them to a generic model like {@link com.azure.digitaltwins.core.implementation.serialization.BasicRelationship}.
+     * @param <T> The generic type to convert the relationship to.
+     * @return A {@link PagedIterable} of relationships belonging to the specified digital twin and the http response.
+     */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
+    public <T> PagedIterable<T> listRelationships(String digitalTwinId, Class<T> clazz) {
+        return listRelationships(digitalTwinId, null, clazz, Context.NONE);
+    }
+
+    /**
+     * Gets all the relationships on a digital twin filtered by the relationship name, by iterating through a collection.
+     *
+     * @param digitalTwinId The Id of the source digital twin.
+     * @param relationshipName The name of a relationship to filter to.
+     * @param clazz The model class to convert the relationship to.
+     * @param <T> The generic type to convert the relationship to.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return A {@link PagedIterable} of relationships belonging to the specified digital twin and the http response.
+     */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
+    public <T> PagedIterable<T> listRelationships(String digitalTwinId, String relationshipName, Class<T> clazz, Context context) {
+        return new PagedIterable<>(digitalTwinsAsyncClient.listRelationships(digitalTwinId, relationshipName, clazz, context));
+    }
+
+    /**
+     * Gets all the relationships referencing a digital twin as a target by iterating through a collection.
+     *
+     * @param digitalTwinId The Id of the target digital twin.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return A {@link PagedIterable} of application/json relationships directed towards the specified digital twin and the http response.
+     */
+    @ServiceMethod(returns = ReturnType.COLLECTION)
+    public PagedIterable<IncomingRelationship> listIncomingRelationships(String digitalTwinId, Context context) {
+        return new PagedIterable<>(digitalTwinsAsyncClient.listIncomingRelationships(digitalTwinId, context));
+    }
+
     //==================================================================================================================================================
     // Models APIs
     //==================================================================================================================================================
@@ -168,4 +366,5 @@ public Response<Void> deleteModelWithResponse(String modelId, Context context) {
     }
 
     //TODO: Decommission Model APIs (waiting for Abhipsa's change to come in)
+
 }

sdk/digitaltwins/azure-digitaltwins-core/src/main/java/com/azure/digitaltwins/core/RequestOptions.java

@@ -0,0 +1,41 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.azure.digitaltwins.core;
+
+import com.azure.core.annotation.Fluent;
+
+/**
+ * General request options that are applicable, but optional, for many APIs.
+ */
+@Fluent
+public class RequestOptions {
+
+    private String ifMatch;
+
+    /**
+     * Gets a string representing a weak ETag for the entity that this request performs an operation against, as per RFC7232.
+     * @return A string representing a weak ETag for the entity that this request performs an operation against, as per RFC7232.
+     */
+    public String getIfMatch() {
+        return ifMatch;
+    }
+
+    /**
+     * Sets a string representing a weak ETag for the entity that this request performs an operation against, as per RFC7232.
+     *
+     * <p> The request's operation is performed only if this ETag matches the value maintained by the server,
+     * indicating that the entity has not been modified since it was last retrieved.
+     * To force the operation to execute only if the entity exists, set the ETag to the wildcard character '*'.
+     * To force the operation to execute unconditionally, leave this value null.
+     * If this value is not set, it defaults to null, and the ifMatch header will not be sent with the request.
+     * This means that update and delete will be unconditional and the operation will execute regardless of the existence of the resource. </p>
+     *
+     * @param ifMatch A string representing a weak ETag for the entity that this request performs an operation against, as per RFC7232.
+     * @return The RequestOptions object itself.
+     */
+    public RequestOptions setIfMatch(String ifMatch) {
+        this.ifMatch = ifMatch;
+        return this;
+    }
+}