/
RPC Entity

RPC Entity

Owned by Gidi Shalev (Unlicensed)

Introduction

RPC entities are Plain Java Objects that are used as models for Mainframe and AS400 RPC programs, SOAP Services, Stored Procedures, etc.

Structure

The RPC Entity comprises of three main parts: RPC Field, RPC Part and an enclosing RPC Entity.

RPC Field - is an ordinary Java field annotated with @RpcField annotation. It should represent a field of the backend program.

RPC Fields can be organized with RPC Parts which represent the backend's program structure object. An RPC Part is a Java class or static nested class annotated with @RpcPart  annotation.


The code snippet on the right is an example of the basic RPC Entity structure. RPC Fields are enclosed in the RPC Part (not obligatory) which is then enclosed in the RPC Entity, together with another RPC Field. The hierarchy of the nested Parts is not limited to a specific number of layers or Java static nested classes. An RPC Part can also be defined as a separate class. According to OpenLegacy terminology, this kind of class is called an External RPC Part. An RPC Field can be any Java type in accordance to legacy type conventions.

An enclosing RPC Entity forms a representation of a single backend program (input, output and metadata) that should be executed by the SDK Project.


The definition and behavior of an RPC Entity can be defined by various properties such as @RpcActions, @Actions, @RpcNavigation, etc.


Rpc Entity
@RpcEntity(name="Books", language=Languages.COBOL)
@RpcActions(actions = {
        @Action(action = EXECUTE.class, path = "BOOKS")})
public class Items {

    @RpcField(originalName = "BOOK")
    private Book bookPart;
    
    @RpcPart(name = "InnerRecord", originalName = "INNER-RECORD", displayName = "INNERRECORD")
    public static class Book {

	    @RpcField(length = 16, originalName = "TITLE" legacyType = "Char")
	    private String title;
    
		@RpcField(length=20, originalName ="AUTHOR", legacyType = "Char")
		private String author;

    	@RpcNumericField(minimumValue = -9999, maximumValue = 9999, decimalPlaces = 0)    
    	@RpcField(length = 2, originalName = "ISBN", legacyType = "Binary Integer")
    	private Integer isbn;

   	 	@RpcField(length = 28, originalName = "DESCRIPTION", legacyType = "Char")
    	private String description;

    }
}

RPC Properties


Properties such as @RpcEntity , @RpcField and @RpcPart are structural properties and are used to define how parts of Java code should be treated by OpenLegacy connectors. When a Java class is annotated with one of:  @RpcEntity, @RpcPart, @RpcEntitySuperClass and @RpcPartSuperClasss , the following additional logic is applied during compilation of the Java Class:

  • Generation of getters and setters for each field of the Class;
  • Generation of List<RpcActionDefinition> actions field and its getter/setter;
  • Generation of auxiliary annotations (@JsonIgnore, @XmlAccessorType, @XmlTransient) for hiding actions and other irrelevant fields when serializing to Json and Xml


The behavior of the RpcEntity in run-time can be controlled using the following properties:

  • @RpcActions and @Action
  • RPC Field properties except @Hidden
  • Direction Enum



The following table shows the relationships between RPC properties (annotations) and OpenLegacy RPC Model Classes:


RPC Entity PropertiesRPC Field PropertiesRPC Part Properties
@RpcEntity@RpcField@RpcPart
@RpcEntitySuperClass@RpcBooleanField@RpcPartSuperClass
@RpcNavigation@RpcDateField
@RpcActions

@RpcNumericField


@Action

@RpcList


Languages - Enum@RpcDynamicField

@Hidden



Direction - Enum


Actions

Actions are specified on the entity with the @RpcActions annotation, and contain all the actions that can be performed on the current entity. 

@RpcActions contains an array of @Actions which specify an action. The @Actions annotations comprise a few attributes:

  • The action attribute is mandatory and declares what Action is performed ( READ, EXECUTE, UPDATE, DELETE, GET, POST );
  • The path attribute defines a path to an executable program in the legacy system. This property should be defined to trigger the correct Program/Procedure/REST API.
  • The alias attribute is another option to use the action with the specified alias name
  • The displayName attribute is solely for demonstration.
  • The olCache and olCacheEvict attribute can define cache configurations for a specific action. Read about caching OpenLegacy entities

    RpcActions
    @RpcEntity(name="Items", language=Languages.COBOL)
@RpcActions(actions = {
                @Action(action = SHOW.class, path = ""),
                @Action(action = EXECUTE.class, path = "ITEMS", displayName = "Execute", alias = "execute"
                        )            })
public class Items {
...
}

RPC Field Properties

Each field of the Rpc Entity should be annotated with @RpcField.

@RpcField annotation has multiple attributes that can customize the definition of the current field. Following are some of main attributes used with this annotation:

  • The length attribute define how many bytes will be occupied by this field in the buffer 
  • The originalName attribute describes the name of the field in the backend system
  • The legacyType attribute is used to declare the type of the field in the backend platform. Note: the use of this attribute can vary on different platforms. Please check if this attribute is relevant for the platform on which you are working, before using it.
  • The order attribute is used to override the default order in which Fields will be read during serialization of the Entity.
  • The direction attribute is used to define the field as an Input, Output, Input_Output or Error. The direction attribute is an object of Direction Enum which defines following directions: INPUT, OUTPUT, INPUT_OUTPUT, ERROR and NONE. The default direction is INPUT_OUTPUT.


@RpcBooleanField, @RpcNumericField, @RpcList, etc., can be used alongside with @RpcField annotation.

@RpcBooleanField is used to define boolean fields and set the True and False value to match the backend value platform.

@RpcDateField is used to define date and time format and locale of the backend platform.

@RpcNumericField allows you to define minimum and maximum values, decimal places and display pattern.

@FieldAttribute annotation is used to provide additional metadata about the field

With @RpcList you can define fields that should represent the list structures in the backend platform. The count attribute defines the length of the list. If count is equal 0, than this list is treated as a dynamic list with variable length.

Additional

  • @RpcNavigation annotation defines the category name with the category attribute. This category is used to display the entity for Web solutions.
  • @Hidden is used to hide the annotated field in the View.