[New Feature] Allow client objects to have resource methods

[rdulmina]

Currently, resource methods are only allowed for service objects, with this feature resource methods will be permitted in client objects.

1. Syntax to call resource methods on clients (which will syntactically be an action)

   Syntax change

   resource-method-call-action :=
      expression "->" "/" [resource-access-path] ["." method-name] ["(" arg-list ")"]
   
   resource-access-path :=
      resource-access-segments ["/" resource-access-rest-segment]
      | resource-access-rest-segment
   
   resource-access-segments :=
      resource-access-segment ("/" resource-access-segment ")* 
   
   resource-access-segment :=
      resource-path-segment-name  // same as for definition
      | computed-resource-access-segment
   
   computed-resource-access-segment := "[" expression "]"
   
   resource-access-rest-segment := "[" "..." expression "]"
   

• Simplest form of resource method call action would be

  clientRef ->/
  clientRef ->/games/carrom

• Parts of the path can come from an expression rather than being compile-time known, by using square brackets (as in a mapping constructor):

  var r = check x->/foo/bar/[userId]/baz;

  The static type of userId must be int|string|float|boolean|decimal

• Parameters can be specified:

  var r = check x->/foo/bar(123);

• Parameters can be named as usual:

  var r = check x->/foo/bar(id=123);

• The last segment of a path can be a spread:

  string[] loc;
  var r = check x->/foo/bar/[...expression] ;

  ... expression: must be a subtype of int|string|float|boolean|decimal[]

• A method other than get can be specified using dot like this:

  var r = check x->/foo/bar.post({ value: 1234 });
  var r = check x->/foo/bar.head;

  • The method-name defaults to get if not specified. A missing arg-list is equivalent to an empty (); arguments get defaulted as usual.

  • New STNode needs to be introduced STResourceMethodCallActionNode

  • Probably Need to introduce a new BLangNode BLangResourceMethodInvocation

2. The client object constructor or client class needs to be able to define resource methods.

   • No syntax change is needed since resource methods are already allowed in object-cons and class-def for services.

   • Need to allow resource functions in a client class or object cons from the semantic analyzer.

3. The client object type needs to be able to include resource methods.

   Syntax change

   object-type-descriptor :=
   object-type-quals object {
   object-member-descriptor*
   }
   object-member-descriptor :=
   object-field-descriptor
   | method-decl
   | remote-method-decl
   | resource-method-decl
   | object-type-inclusion

• Constraints (we do not add resource methods to clients with full generality)

  • hierarchical client resource objects are not supported, i.e. resource methods of client objects are not allowed to return client objects.

  • there is no query concept: a single action will perform a single resource method call

Please add your thoughts on this.

[rdulmina]

Introduced 3 new SyntaxTree nodes for resource method call action

        {
            "name": "ResourceMethodCallActionNode",
            "base": "ActionNode",
            "kind": "RESOURCE_METHOD_CALL_ACTION",
            "attributes": [
                {
                    "name": "expression",
                    "type": "ExpressionNode"
                },
                {
                    "name": "rightArrowToken",
                    "type": "Token"
                },
                {
                    "name": "slashToken",
                    "type": "Token"
                },
                {
                    "name": "resourceAccessPath",
                    "type": "Node",
                    "occurrences": "MULTIPLE"
                },
                {
                    "name": "dotToken",
                    "type": "Token",
                    "isOptional": true
                },
                {
                    "name": "methodName",
                    "type": "SimpleNameReferenceNode",
                    "isOptional": true
                },
                {
                    "name": "arguments",
                    "type": "ParenthesizedArgList",
                    "isOptional": true
                }
            ]
        },
        {
            "name": "ComputedResourceAccessSegmentNode",
            "base": "Node",
            "kind": "COMPUTED_RESOURCE_ACCESS_SEGMENT",
            "attributes": [
                {
                    "name": "openBracketToken",
                    "type": "Token"
                },
                {
                    "name": "expression",
                    "type": "ExpressionNode"
                },
                {
                    "name": "closeBracketToken",
                    "type": "Token"
                }
            ]
        },
        {
            "name": "ResourceAccessRestSegmentNode",
            "base": "Node",
            "kind": "RESOURCE_ACCESS_REST_SEGMENT",
            "attributes": [
                {
                    "name": "openBracketToken",
                    "type": "Token"
                },
                {
                    "name": "ellipsisToken",
                    "type": "Token"
                },
                {
                    "name": "expression",
                    "type": "ExpressionNode"
                },
                {
                    "name": "closeBracketToken",
                    "type": "Token"
                }
            ]
        }

Since we have already allowed resource methods in object types in the parser and logged the error in BLangNodeBuilder there is no need of parser changes to add resource methods to object types.

@lochana-chathura @sameerajayasoma @hasithaa Kindly have a look at this

[lochana-chathura]

@rdulmina and I are thinking of using a single node for ComputedResourceAccessSegmentNode and ResourceAccessRestSegmentNode while making the ... token optional.

We have used a single node in the past for the following similar scenario:

resource-path-segment-param := [[annots] type-descriptor param-name]
resource-path-rest-param := [[annots] type-descriptor ... param-name]

Here the common node name has been taken as ResourcePathParameterNode.

But we cannot use ResourceAccessSegmentNode in this case as we have a different meaning for the resource-access-segment.
Need to figure out a name.

[rdulmina]

Implemented an inner class named BLangResourceMethodInvocation inside BLangInvocation to represent the resource method call action.

    /**
     * @since 2201.2.0
     */
    public static class BLangResourceMethodInvocation extends BLangInvocation implements ActionNode {
        
        public boolean invokedInsideTransaction = false;
        public List<BLangExpression> resourceAccessPathSegments;
        public BLangExpression resourceAccessRestSegment;
        
        @Override
        public void accept(BLangNodeVisitor visitor) {
            visitor.visit(this);
        }

        @Override
        public <T> void accept(BLangNodeAnalyzer<T> analyzer, T props) {
            analyzer.visit(this, props);
        }

        @Override
        public <T, R> R apply(BLangNodeTransformer<T, R> modifier, T props) {
            return modifier.transform(this, props);
        }
    }

[KRVPerera]

It will be better if we can populate resourceAccessPathSegments after we know it's capacity with proper size. This is also okay as this is the current practice. Not having a default array list may encourage proper usage.

[rdulmina]

Updated

[rdulmina]

Update on BLangResourceMethodInvocation inner class.

Removed resourceAccessRestSegment field from BLangResourceMethodInvocation class since resourceAccessRestSegment is converted to BLangListConstructorSpreadOpExpr and added to resourceAccessPathSegments list itself.

    /**
     * @since 2201.2.0
     */
    public static class BLangResourceMethodInvocation extends BLangInvocation implements ActionNode {
        
        public boolean invokedInsideTransaction = false;
        public List<BLangExpression> resourceAccessPathSegments;
        
        @Override
        public void accept(BLangNodeVisitor visitor) {
            visitor.visit(this);
        }

        @Override
        public <T> void accept(BLangNodeAnalyzer<T> analyzer, T props) {
            analyzer.visit(this, props);
        }

        @Override
        public <T, R> R apply(BLangNodeTransformer<T, R> modifier, T props) {
            return modifier.transform(this, props);
        }
    }