Package dev.cel.common

Class CelContainer.Builder

  • Enclosing class:
    CelContainer
    public abstract static class CelContainer.Builder
extends java.lang.Object
    Builder for CelContainer

    • Constructor Detail

      • Builder

        public Builder()

    • Method Detail

      • setName

        public abstract CelContainer.Builder setName​(java.lang.String name)
        Sets the fully-qualified name of the container.

      • addAbbreviations

        @CanIgnoreReturnValue
public CelContainer.Builder addAbbreviations​(com.google.common.collect.ImmutableSet<java.lang.String> qualifiedNames)
        Configures a set of simple names as abbreviations for fully-qualified names.

        An abbreviation is a simple name that expands to a fully-qualified name. Abbreviations can be useful when working with variables, functions, and especially types from multiple namespaces: 

        
 // CEL object construction
 qual.pkg.version.ObjTypeName{
   field: alt.container.ver.FieldTypeName{value: ...}
 }

        Only one the qualified names above may be used as the CEL container, so at least one of these references must be a long qualified name within an otherwise short CEL program. Using the following abbreviations, the program becomes much simpler: 

        
 // CEL Java option
 CelContainer.newBuilder().addAbbreviations("qual.pkg.version.ObjTypeName", "alt.container.ver.FieldTypeName").build()
 
 
 // Simplified Object construction
 ObjTypeName{field: FieldTypeName{value: ...}}

        There are a few rules for the qualified names and the simple abbreviations generated from them:

        • Qualified names must be dot-delimited, e.g. `package.subpkg.name`.
        • The last element in the qualified name is the abbreviation.
        • Abbreviations must not collide with each other.
        • The abbreviation must not collide with unqualified names in use.

        Abbreviations are distinct from container-based references in the following important ways:

        • Abbreviations must expand to a fully-qualified name.
        • Expanded abbreviations do not participate in namespace resolution.
        • Abbreviation expansion is done instead of the container search for a matching identifier.
        • Containers follow C++ namespace resolution rules with searches from the most qualified name to the least qualified name.
        • Container references within the CEL program may be relative, and are resolved to fully qualified names at either type-check time or program plan time, whichever comes first.

        If there is ever a case where an identifier could be in both the container and as an abbreviation, the abbreviation wins as this will ensure that the meaning of a program is preserved between compilations even as the container evolves.

        Throws:
        java.lang.IllegalArgumentException - If qualifiedName is invalid per above specification.

      • addAlias

        @CanIgnoreReturnValue
public CelContainer.Builder addAlias​(java.lang.String alias,
                                     java.lang.String qualifiedName)
        Alias associates a fully-qualified name with a user-defined alias.

        In general, addAbbreviations(java.lang.String...) is preferred to aliasing since the names generated from the Abbrevs option are more easily traced back to source code. Aliasing is useful for propagating alias configuration from one container instance to another, and may also be useful for remapping poorly chosen protobuf message / package names.

        Note: all the rules that apply to abbreviations also apply to aliasing.

        Note: It is also possible to alias a top-level package or a name that does not contain a period. When resolving an identifier, CEL checks for variables and functions before attempting to expand aliases for type resolution. Therefore, if an expression consists solely of an identifier that matches both an alias and a declared variable (e.g., short_alias), the variable will take precedence and the compilation will succeed. The alias expansion will only be used when the alias is a prefix to a longer name (e.g., short_alias.TestRequest) or if no variable with the same name exists, in which case using the alias as a standalone identifier will likely result in a compilation error.

        Parameters:
        alias - Simple name to be expanded. Must be a valid identifier.
        qualifiedName - The fully qualified name to expand to. This may be a simple name (e.g. a package name) but it must be a valid identifier.