sdk/fidl/fuchsia.component.decl/collection.fidl

// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.component.decl;

/// Statically declares a component instance collection.
type Collection = table {
    /// The name of the collection. Instances created in the collection are
    /// scoped to this name.
    1: name name;

    /// The durability of instances in the collection.
    2: durability Durability;

    /// The environment assigned to child instances in this collection.
    ///
    /// Must be non-empty, reference an environment defined in the containing
    /// `ComponentDecl`, and contain only the following characters:
    /// [a-z0-9-_.].
    3: environment name;

    /// The kinds of offers that can target the child instances in this
    /// collection. The default value is `STATIC_ONLY`.
    ///
    /// Only components using the `dynamic_offers` restricted feature may set
    /// this field.
    4: allowed_offers AllowedOffers;

    /// Whether child instances in this collection can have names longer than
    /// the default length limit of 100.
    ///
    /// Only components using the `allow_long_names` restricted feature may set
    /// this field.
    5: allow_long_names bool;

    /// Whether the data in isolated storage used by dynamic child instances and
    /// their descendants will persist after the instances are destroyed. New
    /// dynamic instances inherit the previous instances' data stores.
    ///
    /// This setting can be overridden by a lower-level collection that is a
    /// descendant of a collection that enables/disables this setting.
    ///
    /// This setting applies to all storage capabilities consumed by the
    /// collection components and their descendants.
    ///
    /// The default is the value inherited from an ancestral collection if set,
    /// otherwise `false`.
    6: persistent_storage bool;
};

/// The durability of component instances created in a collection.
type Durability = strict enum {
    /// An instance exists until either it or its parent is destroyed.
    PERSISTENT = 1;
    /// An instance exists until either its parent instance is stopped
    /// or it is explicitly destroyed.
    TRANSIENT = 2;
    /// An instance is started upon creation and is immediately destroyed when
    /// it stops.
    SINGLE_RUN = 3;
};

/// The kinds of offers that can target the children in a collection.
type AllowedOffers = strict enum {
    /// Only static offers may target components in the collection. "Static
    /// offers" are the offers in the `ComponentDecl` that target the collection
    /// itself.
    ///
    /// This is the default behavior.
    STATIC_ONLY = 1;

    /// Both static offers and dynamic offers may target components in the
    /// collection. "Static offers" are the offers in the `ComponentDecl` that
    /// target the collection itself. "Dynamic offers" are additional offers
    /// that are passed to `CreateChild` at runtime.
    STATIC_AND_DYNAMIC = 2;
};