MuranoPL Metadata¶

Define metadata classes¶

Define MuranoPL class with the description of arbitrary metadata. The class that can be used as metadata differs from the regular class:

• The Usage attribute of the former equals to Meta, while the Usage attribute of the latter equals to Class. The default value of the Usage attribute is Class.
• Metadata class has additional attributes (Cardinality, Applies and Inherited) to control how and where instances of that class can be attached.

Name: MetaClassOne
Usage: Meta
Cardinality: One
Applies: All

Properties:
  description:
    Contract: $.string()
    Default: null

  count:
    Contract: $.int().check($ >= 0)
    Default: 0

Name: MetaClassMany
Usage: Meta
Cardinality: Many
Applies: [Property, Method]
Inherited: true

Properties:
  description:
    Contract: $.string()
    Default: null

  count:
    Contract: $.int().check($ >= 0)
    Default: 0

Attach metadata to a MuranoPL entity¶

To attach metadata to MuranoPL class, package, property, method or method argument, add the Meta keyword to its description. Under the description, specify a list of metadata class instances which you want to attach to the entity. To attach only one metadata class instance, use a single scalar instead of a list.

Consider the example of attaching previously defined metadata to different entities in a class definition:

Namespaces:
  =: io.murano.bar
  std: io.murano
  res: io.murano.resources
  sys: io.murano.system


Name: Bar

Extends: std:Application

Meta:
  MetaClassOne:
    description: "Just an empty application class with some metadata"
    count: 1

Properties:
  name:
    Contract: $.string().notNull()
    Meta:
      - MetaClassOne:
          description: "Name of the app"
          count: 1
      - MetaClassMany:
          count: 2
      - MetaClassMany:
          count: 3

Methods:
  initialize:
    Body:
      - $._environment: $.find(std:Environment).require()
    Meta:
      MetaClassOne:
        description: "Method for initializing app"
        count: 1

  deploy:
    Body:
      - If: not $.getAttr(deployed, false)
        Then:
          - $._environment.reporter.report($this, 'Deploy started')
          - $._environment.reporter.report($this, 'Deploy finished')
          - $.setAttr(deployed, true)

The Bar class has an instance of metadata class MetaClassOne attached. For this, the Meta keyword is added to the Bar class description and the instance of the MetaClassOne class is specified under it. This instance’s properties are description and count.

There are three meta-objects attached to the name property of the Bar class. One of it is a MetaclassOne object and the other two are MetaClassMany objects. There can be more than one instance of MetaClassMany attached to a single entity since the Cardinality attribute of MetaClassMany is set to Many.

The initialize method of Bar also has its metadata.

To attach metadata to the package, add the Meta keyword to manifest.yaml file.

Example:

Format: 1.0
Type: Application
FullName: io.murano.bar.Bar
Name: Bar
Description: |
    Empty Description
Author: author
Tags: [bar]
Classes:
    io.murano.bar.Bar: Bar.yaml
    io.murano.bar.MetaClassOne: MetaClassOne.yaml
    io.murano.bar.MetaClassMany: MetaClassMany.yaml
Supplier:
 Name: Name
 Description: Description
 Summary: Summary
Meta:
 io.murano.bar.MetaClassOne:
   description: "Just an empty application with some metadata"
   count: 1

Obtain metadata in runtime¶

Metadata can be accessed from MuranoPL using reflection capabilities and from Python code using existing YAQL mechanism.

The following example shows how applications can access attached metadata:

Namespaces:
  =: io.murano.bar
  std: io.murano
  res: io.murano.resources
  sys: io.murano.system

Name: Bar

Extends: std:Application

Meta:
  MetaClassOne:
    description: "Just an empty application class with some metadata"

Methods:
  sampleAction:
    Scope: Public
    Body:
      - $._environment.reporter.report($this, typeinfo($).meta.
          where($ is MetaClassOne).single().description)

The sampleAction method is added to the Bar class definition. This makes use of metadata attached to the Bar class.

The information about the Bar class is received by calling the typeinfo function. Then metadata is accessed through the meta property which returns the collection of all meta attached to the property. Then it is checked that the meta is a MetaClassOne object to ensure that it has description. While executing the action, the phrase “Just an empty application class with some metadata” is reported to a log. Some advanced usages of MuranoPL reflection capabilities can be found in the corresponding section of this reference.

By using metadata, an application can get information of any type attached to any object and use this information to change its own behavior. The most valuable use-cases of metadata can be:

• Providing information about capabilities of application and its parts
• Setting application requirements

Capabilities can include version of software, information for use in UI or CLI, permissions, and any other. Metadata can also be used in requirements as a part of the contract.

The following example demonstrates the possible use cases for the metadata:

Name: BlogApp

Meta:
  m:SomeFeatureSupport:
    support: true

Properties:
  volumeName:
    Contract: $.string().notNull()
    Meta:
      m:Deprecated:
        text: "volumeName property is deprecated"
  server:
    Contract: $.class(srv:CoolServer).notNull().check(typeinfo($).meta.
               where($ is m:SomeFeatureSupport and $.support = true).any())

Methods:
  importantAction:
    Scope: Public
    Meta:
      m:CallerMustBeAdmin

Note, that the classes in the example do not exist as of Murano Mitaka, and therefore the example is not a real working code.

The SomeFeatureSupport metadata with support: true says that the BlogApp application supports some feature. The Deprecated metadata attached to the volumeName property informs that this property has a better alternative and it will not be used in the future versions anymore. The CallerMustBeAdmin metadata attached to the importantAction method sets permission to execute this method to the admin users only.

In the contract of the server property it is specified that the server application must be of the srv:CoolServer class and must have the attached meta-object of the m:SomeFeatureSupport class with the support property set to true.