Fantom

 

Facets

Overview

Facets are a mechanism to annotate pods, types, and slots with arbitrary meta-data. Facets are similar to Java annotations or C# attributes. A facet is simply a name/value pair where the name is keyed by a symbol an the value is a serializable object.

Syntax

Facets are defined as "@symbolName=value" prefixed before a pod, type, or slot definition:

@serializable
@sys::js  // using qualified symbol
@icon=`/icons/account.png`
@version=Version("1.2")
@table=Table { name="Accounts"; autoCreate=true }
@todo=["fix it", "really fix it"]
class Account
{
}

The symbol can be qualified or unqualified (see Symbols) The symbol type defines the valid type of a facet. For example @sys::uriScheme if defined as a Str, therefore all facets which use this symbol must have a Str value.

If the value is omitted as it is for serializable, then the value is assumed to be true. The other facets illustrate various value types: icon is a Uri literal, version is a simple, table is a complex, and todo is a list. You can create arbitrarily complex facet values through the serialization syntax.

API

Facets are available at runtime via the following methods:

Always prefer the facet method over facets since it is much more efficient. Some examples:

// get a description string
Type.of(obj).facet(@description)

// check if an object implements the simple facet
Type.of(obj).facet(@simple, false) == true

If querying type facets, you can use the inherited parameter to search facets in the inheritance chain:

// check if an object or any of its super-types has the obsolete facet
Type.of(obj).facet(@obsolete, null, true)

Facet Indexing

Type facets can be indexed in the type database to allow efficient queries on the installed types. See Facet Indexing for details.