Module: Jsii::Kernel::Api

Included in:
Jsii::Kernel
Defined in:
jsii/kernel/api.rb

Overview

Core public APIs exposed by the Kernel to interact with JSII

Instance Method Summary collapse

Instance Method Details

#call_method(objref, method, args = []) ⇒ Object

Invoke an instance method on a previously-created JSII object.

Parameters:

  • objref (String, Jsii::Object) —

    the receiver or its $jsii.byref handle.

  • method (String) —

    the JSII method name (camelCase wire form).

  • args (Array) (defaults to: []) —

    positional arguments (Ruby values, serialized internally).

Returns:

  • (Object) —

    the method's return value (deserialized to native Ruby).



55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'jsii/kernel/api.rb', line 55

def call_method(objref, method, args = [])
  objref_payload = if objref.respond_to?(:jsii_serialize)
    objref.jsii_serialize
  else
    { '$jsii.byref' => objref }
  end

  response = request({
    api: 'invoke',
    objref: objref_payload,
    method: method,
    args: Jsii::Serializer.dump(args)
  })

  # Unpack the actual returned value
  Jsii::Serializer.load(response['result'])
end

#call_static(fqn, method, args = []) ⇒ Object

Invoke a static method on a JSII class.

Parameters:

  • fqn (String) —

    fully-qualified name of the class.

  • method (String) —

    the JSII static method name.

  • args (Array) (defaults to: []) —

    positional arguments (Ruby values, serialized internally).

Returns:

  • (Object) —

    the method's return value (deserialized to native Ruby).



120
121
122
123
124
125
126
127
128
 
# File 'jsii/kernel/api.rb', line 120

def call_static(fqn, method, args = [])
  response = request({
    api: 'sinvoke',
    fqn: fqn,
    method: method,
    args: Jsii::Serializer.dump(args)
  })
  Jsii::Serializer.load(response['result'])
end

#create_object(fqn, args = [], overrides: [], interfaces: [], instance: nil) ⇒ String

Instantiate a JSII object in the sidecar and return its by-reference id. The instance: argument (if provided) is pushed — together with the fqn the request is issued with — onto the per-thread pending-object stack for the duration of the call so that callbacks the kernel fires during construction can resolve back to the Ruby instance even though the registry hasn't seen the new ref yet (the fqn lets find_by_ref reject unknown refs of unrelated types).

Parameters:

  • fqn (String) —

    fully-qualified name of the class to construct.

  • args (Array) (defaults to: []) —

    positional constructor arguments (Ruby values, serialized internally).

  • overrides (Array<Hash>) (defaults to: []) —

    override descriptors emitted by the generator / discovered at runtime.

  • interfaces (Array<String>) (defaults to: []) —

    additional interface FQNs the instance implements.

  • instance (Jsii::Object, nil) (defaults to: nil) —

    the in-flight Ruby instance to expose to callbacks.

Returns:

  • (String) —

    the $jsii.byref handle for the new object.



37
38
39
40
41
42
43
44
45
46
47
 
# File 'jsii/kernel/api.rb', line 37

def create_object(fqn, args = [], overrides: [], interfaces: [], instance: nil)
  push_pending_object(instance, fqn)
  begin
    payload = create_object_payload(fqn, args, overrides: overrides, interfaces: interfaces)
    response = request(payload)
    # The Node sidecar returns the true tracking ID, let's use it directly
    response['$jsii.byref']
  ensure
    pop_pending_object
  end
end

#get_property(objref, property) ⇒ Object

Read an instance property on a JSII object.

Parameters:

  • objref (String, Jsii::Object) —

    the receiver or its $jsii.byref handle.

  • property (String) —

    the JSII property name (camelCase wire form).

Returns:

  • (Object) —

    the property value (deserialized to native Ruby).



78
79
80
81
82
83
84
85
86
87
88
89
90
91
 
# File 'jsii/kernel/api.rb', line 78

def get_property(objref, property)
  objref_payload = if objref.respond_to?(:jsii_serialize)
    objref.jsii_serialize
  else
    { '$jsii.byref' => objref }
  end

  response = request({
    api: 'get',
    objref: objref_payload,
    property: property
  })
  Jsii::Serializer.load(response['value'])
end

#get_static(fqn, property) ⇒ Object

Read a static property on a JSII class.

Parameters:

  • fqn (String) —

    fully-qualified name of the class.

  • property (String) —

    the JSII static property name.

Returns:

  • (Object) —

    the property value (deserialized to native Ruby).



135
136
137
138
139
140
141
142
 
# File 'jsii/kernel/api.rb', line 135

def get_static(fqn, property)
  response = request({
    api: 'sget',
    fqn: fqn,
    property: property
  })
  Jsii::Serializer.load(response['value'])
end

#load_assembly(name, version, tarball) ⇒ Hash

Tell the sidecar to load a JSII assembly from a tarball.

Parameters:

  • name (String) —

    npm-style package name (e.g. "jsii-calc").

  • version (String) —

    semantic version of the assembly.

  • tarball (String) —

    absolute path to the .jsii.tgz tarball.

Returns:

  • (Hash) —

    the kernel's ok response envelope.

Raises:



14
15
16
17
18
19
20
21
 
# File 'jsii/kernel/api.rb', line 14

def load_assembly(name, version, tarball)
  request({
    api: 'load',
    name: name,
    version: version,
    tarball: tarball
  })
end

#set_property(objref, property, value) ⇒ Hash

Write an instance property on a JSII object.

Parameters:

  • objref (String, Jsii::Object) —

    the receiver or its $jsii.byref handle.

  • property (String) —

    the JSII property name (camelCase wire form).

  • value (Object) —

    the value to assign (Ruby value, serialized internally).

Returns:

  • (Hash) —

    the kernel's ok response envelope.



99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'jsii/kernel/api.rb', line 99

def set_property(objref, property, value)
  objref_payload = if objref.respond_to?(:jsii_serialize)
    objref.jsii_serialize
  else
    { '$jsii.byref' => objref }
  end

  request({
    api: 'set',
    objref: objref_payload,
    property: property,
    value: Jsii::Serializer.dump(value)
  })
end

#set_static(fqn, property, value) ⇒ Hash

Write a static property on a JSII class.

Parameters:

  • fqn (String) —

    fully-qualified name of the class.

  • property (String) —

    the JSII static property name.

  • value (Object) —

    the value to assign (Ruby value, serialized internally).

Returns:

  • (Hash) —

    the kernel's ok response envelope.



150
151
152
153
154
155
156
157
 
# File 'jsii/kernel/api.rb', line 150

def set_static(fqn, property, value)
  request({
    api: 'sset',
    fqn: fqn,
    property: property,
    value: Jsii::Serializer.dump(value)
  })
end