This chapter uses the UIM Reference Web Service as an example that you can extend.

The UIM Reference Web Service is part of the UIM Software Developer's Kit (SDK). The UIM SDK provides the resources required to build an Inventory cartridge in Design Studio. For more information about the UIM SDK, see "Overview" in UIM Developer's Guide.

This chapter assumes you are using Design Studio to develop custom rest web services. If you use an integrated development environment (IDE) other than Design Studio, you can ignore the .classpath and .project files in the reference_rest_webservice.zip file.

You can view the contents of reference_rest _webservice.zip file in Oracle Communications Service Catalog and Design – Design Studio by importing the archive ZIP file into Design Studio. The ZIP file contains several types of files including the following:

• YAML Files:

  The UIMSample1_0.yaml file defines a sample web service operation. The YAML file also defines the paths that defines individual API endpoints and HTTP methods (GET, POST, PATCH, DELETE), components, parameters and payload of operation. See "About the YAML File" for more information about the UIMSample1_0.yaml file.

• Java Source Files :

  The Java source files provide the web service operation code. For example, these source files provide the following:

  • Model files generated out of components mentioned in yaml
  • An API manager to call UIM core for the operation
  • Transaction management for the operation with the commit or rollback results

  See "Developing the REST Web Service" for more information about the Java source files that includes the list and descriptions for each type of the class files, and information about the files that need to be created or modified.

• Gradle Build File:

  The build.gradle file defines Gradle targets that you can run to build a custom REST web service. Gradle targets are a set of executable tasks defined in the build.gradle file. See "About the Gradle Build File" for more information.

You require the following prerequisites for customizing REST web services:

• Install Gradle. See “Installing Gradle” for more information.
• Set up a proxy. See “Setting Up Proxy” for more information.
• Update the properties file from reference_rest_webservice/etc/<COMPUTERNAME>.properties

The Reference REST web service operation is defined by the UIMSample1_0.yaml file. The YAML file is located at UIM_SDK_Home/webservices/reference_rest_webservice.zip\yaml, where UIM_SDK_Home is the local directory for UIM SDK.

The YAML file defines the REST web service operation. The operation defines a requestBody, parameters, and all possible server responses. For example, the YAML file defines the following for the createInventoryGroup operation with HTTP method POST:

The request contains all possible responses where each response defines a JSON structure that is defined in the supporting schemas.

The following example shows the path definition, operation, and the input request message within a Sample YAML file:

paths:
  /inventoryGroup:
    post:
      operationId: createInventoryGroup
      summary: Create Ig
      description: |
        Creates a inventory group with the given details
      tags:
        - Sample Inventory Group
      requestBody:
        description: The ig to create.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryGroup'
      responses:
        '201':
          description: The ig were created successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InventoryGroup'
        '400':
          description: The request isn't valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: You aren't authorized to make this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The request is forbidden.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: An internal server error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
.
.
.
components:
  schemas:
    InventoryGroup:
      type: object
      description: A inventoryGroup to associate with the resource.
      properties:
        id:
          type: string
          description: The ID of the ig.
          readOnly: true
        href:
          type: string
          format: uri
          description: The URI for the ig.
        name:
          type: string
          description: The name of the resource.
        description:
          type: string
          description: A free-text description for the resource. 
        igSpecification:
          $ref: 'Combined.yaml#/components/schemas/Specification'
        startDate:
          type: string
          description: The date and time when the time period starts.
          format: date-time
        endDate:
          type: string
          description: The date and time when the time period ends.
          format: date-time
        place:
          type: array
          items:
            $ref: 'Combined.yaml#/components/schemas/PlaceRef'
          description: The list of associated geographic places.
        parentGroupRef:
          type: array
          items:
            $ref: '#/components/schemas/GroupRef'
        inventoryGroupItems:
          type: array
          items:
            $ref: '#/components/schemas/GroupItemRef'
          description: The list of associated inventory group items.

The above example shows a model schema for InventoryGroup which is the used as the request body with Content-Type : application/json. For the response, with SUCCESS (20x), the same schema of InventoryGroup appears. The error model mentioned in the example is for the error codes.

For more details on OpenApi structure, see https://swagger.io/docs/specification/about/

The build.gradle file defines Gradle targets that you can run to build a custom web service. These build targets are a set of executable tasks that help in building a web service.

Table 5-1 describes the Gradle targets defined in the build.gradle file. See "Developing Custom REST Web Services" for information about when to run these Gradle targets, the Gradle commands that you should run, and the project to be imported to Design Studio.

For more information on Gradle, see https://docs.gradle.org/current/userguide/userguide.html

This section describes the guidelines for developing a REST web service. It explains class diagrams that represent the UIM Reference REST Web Service development classes.

You use the Design-First approach to develop custom REST web services.

Description of the illustration developing-custom-web-services.png

The Design-first approach is as follows:

• Define YAML with paths and components. Write the YAML to define the operations and data.
• Yaml-to-Java generation: Use the build.gradle Gradle targets provided by the Reference REST web service to generate Java source files, based on the YAML.
• Develop a Java web service interface implementation: Use the web service development environment and tools provided by the Reference REST web service to implement the web service interface by creating new Java source files and changing the existing files.

For example, the UIM Reference Rest Web Service module is designed using the Design-first approach. This means that:

• The InventoryGroupApiServiceImpl, InventoryGroupApiService, and InventoryGroupType Java source files are generated based on the YAML (Swagger Code generator). This generation results in the YAML operation being defined in the Java source file, but with no coding details as a sample template.
• The build generates model, api, impl Java sources.

The Reference web service performs transaction actions in a specific order while managing operation transactions.

To manage the transaction, you write code that performs the following steps:

1. Start the user environment.
2. Start the transaction.
3. Set the user environment on the transaction.
4. Set up the request, call the API method on the entity manager class, and manage the response.
5. Commit or rollback the transaction.
6. (Optional) Perform a rollback when an error occurs.
7. Ensure the user environment is ended with a call to the endUserEnvironment method on success or failure.

The sample from InventoryGroupApiServiceImpl.java is as follows:

UserEnvironment userEnvironment = null;
          InventoryTransactionValue transValue = null;
          InventoryGroupManager lgManager = PersistenceHelper.makeInventoryGroupManager();
		  InventoryGroup result = null;
		  InventoryGroupType resource = null;
          try {
              userEnvironment = startUserEnvironment(restUtils.getHttpRequest());
              transValue = startTransaction();
              transValue.setUserEnvironment(userEnvironment);
            ……….
             result = lgManager.createInventoryGroup(ig);
           …………………
finally {
            commitOrRollback(transValue);

Developing a new web service involves generating new model file, new API file, new API impl file, and creating new Java source files. After you create these files, you should copy model file, API file, and API impl file to the corresponding paths within the reference_rest_webservice directory.

This section provides information about creating and copying these files.

A WAR file contains the compiled classes from the developed custom web service.

Before creating a WAR file, copy all JAR files that are pulled by Gradle into the reference_rest_webservice\lib folder, which can be used as CART\lib, as follows:

gradlew copyLibs

To create a WAR file with Model, API, and API impl, run the following command:

gradlew war

You can customize the name for the WAR file by updating the COMPUTERNAME.properties file. The generated WAR file resides in the reference_rest_webservice/build/libs directory.

The Reference REST Web Service WAR file is not packaged in the inventory.ear file and is therefore not automatically deployed into UIM. Rather, you must manually import the provided WAR file into an EAR file to deploy.

In UIM traditional deployments, when developing custom web services, you have the option of packaging the custom web service WAR file into:

• The custom.ear file: If you develop a single custom web service, Oracle recommends you use the provided custom.ear file.
• Any custom EAR files: If you develop multiple custom web services, Oracle recommends you use a separate custom EAR for each web service. This approach involves additional development work as you must create and configure your message queue and corresponding listener class. It is suitable for multiple custom web services and provides a better performance.

If you have placed your custom REST web service in the custom.ear file, or in any custom EAR file, you must specify a deployment plan for the updated EAR file.

To specify a deployment plan:

1. Log in to the WebLogic Server Administration Console.
2. In the left panel, under Domain Structure, click Deployments.

   The Summary of Deployments page appears.

3. In the left panel, under Change Center, click Lock & Edit.
4. Select the check box next to the updated EAR file that contains your custom web service.
5. Click Update.

   The Update Application Assistant page appears.

6. Click Change Path and then click Next.

   The deployment plan is specified and custom.ear is redeployed.