Framework Support for Java Entity CUD

Background

With this enhancement, entities with the JAVA implementation type will now gain full support for CUD operations.

Java Entities will be managed similarly to regular PL/SQL Entities. For instance, entity key validations previously performed in the PL/SQL layer must also be implemented in the Java layer. The OData provider will not validate the request payload for required fields, leaving this responsibility to the Java implementation layer.

Entity Definition

The entity model should have all the keys, while the fragment or projection layer can define attributes based on specific requirements.

attributes {
   key      CUDKey      NUMBER      KMI-L;
}

Additionally, the Entity Services should be disabled to handle data consistency in Java Entity CUD operations by utilizing the following codegen property.

codegenproperties {
    ExposeEntityAsService "false";
}

Entity Annotation

To enable Java Entity CUD (Create, Update, Delete) functionality, start by overriding the Entity. Then, the projection developer should annotate the Entity within the projection or fragment as shown below, with the "crud" options selected based on the requirements. This approach ensures the generation of the corresponding Java implementation for the specified Entity CUD operations.

@Override
entity ActionBase {
    crud = create, update, delete {
        implementation = "Java";
    }
}

Implementing Java Entity Operations

Once the code is generated, projection developers have stubs for each operation type, which include two parameters: a Java Map and a database connection. The response to the OData provider should be structured as follows:

• For Create and Update operations: Return a Map containing the CUD operation name and the details of the created or updated entity in JSON format, converted to an input stream.
• For Delete operations: Return a simple success message indicating the operation's completion.

public class JavaCUDTestEntitiesImpl implements JavaCUDTestEntities {
    @Override
    public Map<String, Object> createEntityName(final Map<String, Object> parameters, final Connection connection) {
      Map<String, Object> response = new LinkedHashMap<>();
      response.put("Create", new ByteArrayInputStream(payload));
      return response;
    }
    @Override
    public Map<String, Object> updateEntityName(final Map<String, Object> parameters, final Connection connection) {
      Map<String, Object> response = new LinkedHashMap<>();
      response.put("Update", new ByteArrayInputStream(payload));
      return response;
    }
    @Override
    public Map<String, Object> deleteEntityName(final Map<String, Object> parameters, final Connection connection) {
      Map<String, Object> response = new LinkedHashMap<>();
      response.put("Delete", new ByteArrayInputStream(payload));
      return response;
    }
}

Parameter Mapping

ODP to Java Implementation

The structure of the Java Map parameter is outlined as follows:

Map {
  "X-IFS-Request-Id": "1",
  "IfsUser": "user",
  "Locale_$": "en",
  "PreferredUsername": "PreferredUsername",
  "ETag": Map {
    "ObjId": "we34qwe3e13",
    "ObjVersion": "20240101"
  },
  "Entity": EntityValue {
    "keys": ["attribute1", "attribute2"],
    "attribute1": "attrValue1",
    "attribute2": "attrValue2",
    "attribute3": "attrValue2"
  },
  "SelectedAttributes": Collection["attr1", …]
}

EntityValue - A Java class offering utility functions for data retrieval, key identification, and related operations(getDecimal(), getStructure(), getAttributes(), etc), provided within the 'com.ifsworld.fnd.odp.api.storage.model' package.

When the If-Match header is set to *

 ObjId: null,
 ObjVersion: *

Java Stub Response to ODP

Map {
  "CUDOperationName(Create/Update/Delete)": ByteArrayInputStreamOf
  JsonObject {
    "ETag": Map {
      "ObjId": "we34qwe3e13",
      "ObjVersion": "20240101"
    },
    "Info": "INFO[char31]This was a Info Message[char30]",
    "Entity": {
      "key1": "key1",
      "key2": "key2"
    }
  }
}

Info Key - Specifies the warnings and informational messages related to the transaction. It should follow the format used in CLIENT_SYS.Add_Info and CLIENT_SYS.Add_Warning.

• Example: INFO[char31]This was a Info Message[char30]

Considerations

• Raise a ProjectionException and include the corresponding HTTP status code in any exception scenario.
• Provide client information through the Info JSON key in the response for all operations where it is needed.
• Include only the entity with its keys and the ETag in the response for Create and Update operations.
• Timestamp values returned from the Java stub should follow the pattern yyyy-MM-dd-HH.mm.ss.