Common class structure¶

Contract¶

Contract is a YAQL expression that says what type of the value is expected for the property as well as additional constraints imposed on a property. Using contracts you can define what value can be assigned to a property or argument. In case of invalid input data it may be automatically transformed to confirm to the contract. For example, if bool value is expected and user passes any not null value it will be converted to True. If converting is impossible exception ContractViolationException will be raised.

The following contracts are available:

In the example below property port must be int value greater than 0 and less than 65536; scope must be a string value and one of ‘public’, ‘cloud’, ‘host’ or ‘internal’, and protocol must be a string value and either ‘TCP’ or ‘UDP’. When user passes some values to these properties it will be checked that values confirm to the contracts.

Namespaces:
  =: io.murano.apps.docker
  std: io.murano

Name: ApplicationPort

Properties:
  port:
    Contract: $.int().notNull().check($ > 0 and $ < 65536)

  scope:
    Contract: $.string().notNull().check($ in list(public, cloud, host, internal))
    Default: private

  protocol:
    Contract: $.string().notNull().check($ in list(TCP, UDP))
    Default: TCP

Methods:
  getRepresentation:
    Body:
      Return:
        port: $.port
        scope: $.scope
        protocol: $.protocol

The template contract does the same validation as the class contract, but does not require the actual object to be passed as a property or argument. Instead it allows to create an object from the given template later. Also you can exclude some of the properties from validation and provide them later in the body of the method.

Consider the following example:

Namespaces:
  =: io.murano.applications
  res: io.murano.resources
  std: io.murano

Name: TemplateServerProvider

Properties:
  template:
    Contract: $.template(res:Instance, excludeProperties => [name]).notNull()
  serverNamePattern:
    Contract: $.string().notNull()
  threshold:
    Contract: $.int().check($ > 0)

Methods:
  createReplica:
    Arguments:
      - index:
          Contract: $.int().notNull()
      - owner:
          Contract: $.class(std:Object)
    Body:
      - If: $index < $this.threshold
        Then:
          - $template: $this.template
          - $template.name: $this.serverNamePattern.format($index)
          - $template['?'].name: format('Server {0}', $index)
          - Return: new($template, $owner)
        Else:
          - Return: null

In the example above the class has the template property that is validated by the template contract. It holds the template of the object of the Instance class or its inheritor. In the createReplica method template is used to dynamically create instances in runtime considering some conditions and customizing the name property of an instance, as it was excluded from validation.

You still can pass an actual object to the property or argument with the template contract, but it will be automatically converted to its object model representation.

Property usage¶

Usage states the purpose of the property. This implies who and how can access it. The following usages are available:

The usage attribute is optional and can be omitted (which implies In).

If the workflow tries to write to a property that is not declared with one of the types above, it is considered to be private and accessible only to that class (and not serialized to output and thus would be lost upon the next deployment). An attempt to read the property that was not initialized results in an exception.

Default¶

Default is a value that is used if the property value is not mentioned in the input object model, but not when it is set to null. Default, if specified, must conform to a declared property contract. If Default is not specified, then null is the default.

For properties that are references to other classes, Default can modify a default value of the referenced objects. For example:

p:
 Contract: $.class(MyClass)
 Default: {a: 12}

This overrides default for the a property of MyClass for instance of MyClass that is created for this property.

Method arguments¶

Arguments are optional too, and are declared using the same syntax as class properties. Same as properties, arguments also have contracts and optional defaults.

Unlike class properties Arguments may have a different set of Usages:

Arguments example:

scaleRc:
  Arguments:
    - rcName:
        Contract: $.string().notNull()
    - newSize:
        Contract: $.int().notNull()
    - rest:
        Contract: $.int()
        Usage: VarArgs
    - others:
        Contract: $.int()
        Usage: KwArgs

Method body¶

The Method body is an array of instructions that get executed sequentially. There are 3 types of instructions that can be found in a workflow body:

• Expressions,
• Assignments,
• Block constructs.

Method usage¶

Usage states the purpose of the method. This implies who and how can access it. The following usages are available:

The Usage attribute is optional and can be omitted (which implies Runtime).

Method scope¶

The Scope attribute declares method visibility. It can have two possible values:

• Session - regular method that is accessible from anywhere in the current execution session. This is the default if the attribute is omitted;
• Public - accessible anywhere, both within the session and from outside through the API call.

The Scope attribute is optional and can be omitted (which implies Session).

Expressions¶

Expressions are YAQL expressions that are executed for their side effect. All accessible object methods can be called in the expression using the $obj.methodName(arguments) syntax.

Assignment¶

Assignments are single key dictionaries with a YAQL expression as a key and arbitrary structure as a value. Such a construct is evaluated as an assignment.

Block constructs¶

Block constructs control a program flow. They are dictionaries that have strings as all their keys.

The following block constructs are available:

Notice, that if you have more than one block construct in your workflow, you need to insert dashes before each construct. For example:

Body:
  - If: predicate1()
    Then:
      - code
      - block
  - While: predicate2()
    Do:
      - code
      - block