json_class: Create and validate JSON class objects

In ropensci/infx: OpenBIS API Access to the InfectX Data Repository

Create and validate JSON class objects

Description

To communicate object type information via JSON to the Jackson-powered openBIS interface, the @type field is used. Data received from openBIS is recursively stripped of @type fields and the type information is saved as class attribute. Such objects also have the class json_class added. The function as_json_class() (or its alias as.json_class()) powers this recursive conversion of a list with filed @type into a json_class object. The constructor json_class() is available for non-recursive instantiation of json_class objects.

Usage

json_class(..., class)

as_json_class(x, ...)

as.json_class(x, ...)

## S3 method for class 'json_class'
as_json_class(x, ...)

## S3 method for class 'list'
as_json_class(x, recursive = TRUE, ...)

## S3 method for class 'json_vec'
as_json_class(x, ...)

## Default S3 method:
as_json_class(x, force = FALSE, ...)

rm_json_class(x, recursive = TRUE, restore_type = TRUE)

## S3 method for class 'json_class'
as.list(x, keep_asis = TRUE,
  recursive = !keep_asis, restore_type = !keep_asis, ...)

is_json_class(x)

is.json_class(x)

check_json_class(x, recursive = TRUE)

Arguments

...	Generic compatibility.
class	JSON sub-class name.
x	Object to process.
recursive	Recursively apply the function.
force	Suppress error when casting an object to json_class that cannot be converted.
restore_type	When removing the json_class information from an object, whether to preserve the subclass attribute as @type filed.
keep_asis	Used in as.list(), if TRUE, the json_class object is returned as-is, if FALSE, class attributes may be dropped/written to the list structure into the @type field.

Details

The action of as_json_class() is reversed by rm_json_class(). This removes both the json_class class attribute and the JSON class attribute itself, which is subsequently written to a @type filed. This preserving of type information can be disabled, by setting the argument restore_type to FALSE. Furthermore, the action can be applied recursively with the argument recursive. The function as.list() can also be used to perform the above actions, but with default arguments, it does nothing, as functions such as base::sapply() and base::lapply(), call as.list().

JSON class objects have custom sub-setting and printing functions available. Sub-setting of JSON objects that preserve class and json_class attributes. This is useful when objects are created from openBIS results which are subsequently used in further queries, but the constructors they are passed to require only a subset of the fetched fields.

The functions is_json_class() tests whether an object is a proper JSON class object, meaning that:

• it is a list

• it inherits json_class

• the last class attribute is json_class

• apart from json_class there exists at least one more class attribute

In order to recursively test a json_class object for being properly formed, the function check_json_class() can be used. This recurses through a list structure and whenever an object inherits from json_class it is tested with is_json_class().

Value

JSON objects are represented as S3 classes with two class attributes: json_class and an object specific class name (typically to mirror the openBIS class).

See Also

Other json object handling functions: has_fields.json_class, json_vec, print.json_class

Examples

lst <- list(`@type` = "foobar",
            a = list(`@type` = "foo", b = "c"),
            d = list(`@type` = "bar", e = "f"))

cls <- as_json_class(lst)
print(cls, depth = 2)

is_json_class(cls)
get_subclass(cls)

# recursive validation of json_class objects with check_json_class()
attr(cls[["d"]], "class") <- "json_class"
is_json_class(cls)
check_json_class(cls)

# as_json_class() is idempotent
identical(as_json_class(lst), as_json_class(as_json_class(lst)))

# rm_json_class() reverses the action of as_json_class()
identical(lst, rm_json_class(as_json_class(lst)))

# json_class objects can be instantiated using the constructor json_class()
identical(as_json_class(lst), 
          json_class(a = json_class(b = "c", class = "foo"),
                     d = json_class(e = "f", class = "bar"),
                     class = "foobar"))

cls <- as_json_class(lst)

# the default of as.list does nothing
identical(cls, as.list(cls))
# this can be disabled, by setting keep_asis to FALSE
identical(lst, as.list(cls, keep_asis = FALSE))
# further options are disabling recursive action
as.list(cls, keep_asis = FALSE, recursive = FALSE)
# and dropping type information
as.list(cls, keep_asis = FALSE, recursive = FALSE, restore_type = FALSE)

ropensci/infx documentation built on May 14, 2022, 5:51 p.m.