/*! * Copyright (c) Microsoft Corporation and contributors. All rights reserved. * Licensed under the MIT License. */ import { ExtractedContext, SerializedChangeSet, Utils } from "@fluid-experimental/property-changeset"; import { SharedPropertyTree } from "@fluid-experimental/property-dds"; import { BaseProperty } from "@fluid-experimental/property-properties"; import { IActivateDataBindingOptions, IDefineRepresentationOptions, IRegisterOnPathOptions, representationGenerator } from "../index.js"; import { ActivationType } from "../internal/activationQueryCacheHelper.js"; import { DataBinderHandle } from "../internal/dataBinderHandle.js"; import { PropertyElement } from "../internal/propertyElement.js"; import { IDefineDataBindingOptions } from "./IDefineDataBindingOptions.js"; import { DataBinding } from "./dataBinding.js"; import { DataBindingRegistry } from "./dataBindingRegistry.js"; import { DataBindingTree, NodeType } from "./dataBindingTree.js"; export interface DataBindingDefinition { bindingType: string; bindingConstructor: typeof DataBinding; typeID: string; splitType: ExtractedContext; } /** * A DataBinder allows one to register a number of bindings for different property types. The * DataBinder can then be bound to * a PropertyTree to have the data bindings created automatically. * * These data bindings are notified of the modification and removal of the underlying property. * * @example * * ```typescript * const databinder = new DataBinder(propertyTree); * databinder.defineDataBinding(...); * * // or * const databinder = new DataBinder(); * databinder.defineDataBinding(...); * // ... * databinder.attachTo(propertyTree); * const workspace = databinder.getPropertyTree(); * // ... * ``` * @internal */ export declare class DataBinder { _dataBinderId: number; _registry: DataBindingRegistry; _onModifiedRegistrationKey: any | undefined; _propertyTree: SharedPropertyTree | undefined; _postProcessingCallbackQueue: Function[]; _dataBindingTree: DataBindingTree; _removedDataBindings: Map; _activationScope: number; _definitionsByBindingType: Map; _activationHandlesByBindingType: Map; _delayedActivationHandles: Set; _representationGenerators: Map; _representationHandlesByBindingType: Map; _buildingStatelessRepresentations: Map; _activeTraversal: boolean; _visitationIndex: number; _currentChangeSetId: number; _dataBindingCreatedCounter: number; _dataBindingRemovedCounter: number; _AbsolutePathDataBinding: typeof DataBinding; dataBinder: any; /** * Constructor for the DataBinder. * @param - The PropertyTree to bind to. */ constructor(propertyTree?: SharedPropertyTree); /** * Registers a stateless data binding. The provided binding will be called for all events on any property that * matches the path rules in the options. * * @param in_bindingType - The type of the binding. (ex. 'VIEW', 'DRAW', 'UI', etc.) * @param in_typeID - The id to use for this registration, usually the type id of the * objects being represented (like a PropertySet template id). * @param in_statelessConstructor - The stateless binding's constructor. Must take a parameter * object as its only argument. * @param in_options - An object containing optional parameters. * * @returns A handle that can be used to unregister this data binding */ registerStateless(in_bindingType: string, in_typeID: string, in_statelessConstructor: DataBinding, in_options?: IActivateDataBindingOptions): DataBinderHandle; /** * Return whether a databinding exists for the given typeID/binding type pair * * Data Bindings are associated with a binding type and a typeID. * * @param in_bindingType - The type of the data binding. (ex. 'BINDING', 'DRAW', 'UI', etc.) * @param in_typeID - The id to use for this registration, usually the type id of the * objects being represented (like a PropertySet template id). * @returns True if and only if there is a binding for this combination */ hasDataBinding(in_bindingType: string, in_typeID: string): boolean; /** * Defines and activates a new data binding. * This function will retroactively create bindings for any properties already present in the workspace that * match the path options provided. * * @deprecated Please use {@link DataBinder.defineDataBinding} and {@link DataBinder.activateDataBinding} instead. * * @param in_bindingType - The type of the data binding. (ex. 'BINDING', 'DRAW', 'UI', etc.) * @param in_typeID - The id to use for this registration, usually the type id of the * objects being represented (like a PropertySet template id). * @param in_bindingConstructor - The constructor for the data binding. Must take a parameter object * as its only argument. * @param in_options - An object containing additional parameters. * * @returns A handle that can be used to unregister this data binding. * @throws Will throw an error if the constructor is missing or invalid. */ register(in_bindingType: string, in_typeID: string, in_bindingConstructor: typeof DataBinding, in_options?: any): DataBinderHandle; /** * Defines a new DataBinding in the DataBinder. No instances are created until activateDataBinding is called for the * bindingType/typeID pair. * * Data Bindings are associated with a binding type and a typeID. These definitions can then be activated using * {@link DataBinder.activateDataBinding}. For a given property, the DataBinder will consider all active DataBindings, * choose the definition that best matches the property type (based on inheritance), and create the binding using * the constructor. * * @param in_bindingType - The type of the data binding. (ex. 'BINDING', 'DRAW', 'UI', etc.) * @param in_typeID - The id to use for this registration, usually the type id of the objects * being represented (like a PropertySet template id). * @param in_bindingConstructor - The constructor for the data binding. Must take a parameter object * as its only argument. * @param in_options - optional options for the new databinding * @returns A handle that can be used to undefine the binding. * @throws If the constructor is missing or invalid. * @throws If the bindingType/typeID pairing is already defined. */ defineDataBinding(in_bindingType: string, in_typeID: string, in_bindingConstructor: typeof DataBinding, in_options?: IDefineDataBindingOptions): DataBinderHandle; /** * Handle callback to unregister a data binding definition. Note; this will not destroy any * bindings that are currently instantiated. * * @param in_handle - the handle that was just destroyed * @param in_definition - the definition of the databinding to unregister * * @hidden */ private _unregisterBindingDefinition; /** * Creates the bindings associated with the bindingType/typeID pair, following the rules for the path defined by * the options. * * For every property that matches the path options that is of type in_typeID, or inherits from type in_typeID, * the DataBinder will look for a DataBinding definition (defined using {@link DataBinder.defineDataBinding}) for * the in_bindingType that best matches the property type. This may be a definition associated with the type or * inherits from this type. * * Only a single DataBinding will be created for a given bindingType/typeID. * * When new properties are later inserted into the workspace that match the path rules in the options, * DataBindings will be created as well. * * @example * @snippet javascript 'test/data_binder/data_binding.spec.js' * SnippetStart{DataBinder.DataBindingInheritance} SnippetEnd{DataBinder.DataBindingInheritance} * * @param in_bindingType - The type of the data binding. (ex. 'BINDING', 'DRAW', 'UI', etc.) * @param in_typeID - The Property template id of the objects being represented. * Properties with this type or inheriting from this type will be * activated for this binding type. * If not given, all bindings for in_bindingType will be activated. * @param in_options - Activation options * * @returns A handle that can be used to deactivate this instance of the binding. See * {@link DataBinderHandle.destroy}. */ activateDataBinding(in_bindingType: string, in_typeID?: string, in_options?: IActivateDataBindingOptions): DataBinderHandle; /** * Deactivates a data binding. * * @param in_handle - The handle returned by the activateDataBinding function * @param in_activationRule - the binding rule associated with the handle - how it was activated * * @private * @hidden */ _deactivateBinding(in_handle: DataBinderHandle, in_activationRule: ActivationType): void; /** * Delay the activation of bindings until {@link DataBinder.popBindingActivationScope}. Multiple * pushBindingActivationScope's can be nested. * * This feature can be used to delay activation when activating multiple data binding definitions * simultaneously. * * This functionality should be used with care, since unbalanced push/pop bracketing can render * the DataBinder permanently disabled. Consider doing push/pop scopes using try/catch blocks, * for example. */ pushBindingActivationScope(): void; /** * Pop the activation scope. When the push and pops balance themselves, any pending * binding activations will be done, and all the corresponding bindings will be created. * * See {@link DataBinder.pushBindingActivationScope}. */ popBindingActivationScope(): void; /** * Check if the system is in a state where the delayed bindings can be installed. * Bindings are delayed until the registration scope is zero, and there is a workspace * attached. * @hidden */ private _checkDelayedBindings; /** * Set/increment a letiable on the data binding that says that it is registered with one or more * DataBinders. This allows DataBinding.registerOnPath to alert the user when they are registering a * path or property to a DataBinding after it is already registered in the manager. * * @param in_bindingConstructor - the constructor to modify * @hidden */ private _markDataBindingAsRegistered; /** * Clear/decrement a letiable on the data binding that says that it is registered with one or more * DataBinders. This allows DataBinding.registerOnPath to alert the user when they are registering a * path or property to a DataBinding after it is already registered in the manager. * * @param in_dataBindingConstructor - the constructor to modify * * @hidden */ private _unmarkDataBindingAsRegistered; /** * Create a traversal context as if we were traversing the hierarchy at this location * * @param in_property - the property at the given path * @param in_traversalPath - the absolute path as a string * @param in_absTokenizedPath - the absolute path, tokenized * @param in_dataBindingTreeNode - the DataBindingTree node at the given path * * @returns a fake traversal context * * @hidden */ private _createFakeTraversalContext; /** * Determine if the provided rule applies to the given property * * @param in_activationSplitType - the split type for what we are activating * @param in_propertySplitType - the split type for the property we are * considering * @param in_definitionSplitType - the split type for the definition we would * apply * * @returns true if the rule applies to this property type * * @hidden */ private _activationAppliesToTypeId; /** * From the given root, builds all the databindings described by the activation rules. The activation * rules have been filtered to be a simple case to visit. * Examples of complicated things: * - if there is an exactPath, we need to make sure that path is not going through a reference, * - a binding may start at a tree X, and another at a subtree X.Y; we need to adjust for that * - there may be an exclusion path * * If these are all removed, we are in a situation where we can just visit all the properties blindly * * @param in_rootPropertyElement - the property element from which to recurse from * @param in_activationRules - the activation rules to apply * @param io_instantiatedBindings - the accumulated bindings created * * @hidden */ _fastCreateRetroactive(in_rootPropertyElement: PropertyElement, in_activationRules: ActivationType[], io_instantiatedBindings: any[]): void; /** * From the given root, builds all the databindings described by the activation rules. * * @param in_rootPropertyElement - the property element from which to recurse from * @param in_activationRules - the activation rules to apply * @param io_instantiatedBindings - the accumulated bindings created * * @hidden */ _generalCreateRetroactive(in_rootPropertyElement: PropertyElement, in_activationRules: ActivationType[], io_instantiatedBindings: DataBinding[]): void; /** * Recursively creates data bindings on existing properties for the provided registration handles. We create them * in a depth-first fashion. * * @param in_activationRules - The array of rules to apply bindings for * * @private * @hidden */ private _createBindingsRetroactively; /** * Remove all the bindings that were created for the provided activation rule. If the binding was created due to * two activations, it will not be removed, it will simply be derefed. * * @param in_activationRule - The description of the activation * * @private * @hidden */ _unbindActiveBindings(in_activationRule: ActivationType): void; /** * Returns all items in the tree corresponding to a certain bindingType. * NOTE: This is very inefficient, and only for internal testing * * @param in_bindingType - name of the bindingType * @returns the found items * @private * @hidden */ _getDataBindingsByType(in_bindingType: string): Array; /** * Registers a handler that is called every time a change affects a given absolute path * that is known to exist and does not contain any references. * * @param in_absolutePath - Path to register the handler for * @param in_operations The operations for which the callback function gets called * (one of 'insert', 'modify', 'remove', 'collectionInsert', 'collectionModify', 'collectionRemove', * 'referenceInsert', 'referenceModify', 'referenceRemove') * @param in_callback - The callback to invoke * @param in_options - Additional user specified options for the * callback and its registration * @returns A handle that can be used to unregister the callback * @private * @hidden */ _registerOnSimplePath(in_absolutePath: string, in_operations: Array, in_callback: Function, in_options?: IRegisterOnPathOptions): DataBinderHandle; /** * Unregisters an absolute path listener. * * @param in_handle - The handle returned by registerOnPath * @param in_registrationInfo - the information describing the registerOnPath, to unregister with. * @hidden */ private _unregisterOnSimplePath; /** * Registers a handler that is called every time a change affects the property at the given path * from the root of the PropertyTree. * * @example * @snippet javascript 'test/data_binder/absolute_path.spec.js' * SnippetStart{DataBinder.registerOnPath} SnippetEnd{DataBinder.registerOnPath} * * @param in_absolutePath - Path(s) to register the handler for, relative to * the root of the PropertyTree * @param in_operations - the operations for which the callback function gets called * (one of 'insert', 'modify', 'remove', 'collectionInsert', 'collectionModify', 'collectionRemove', * 'referenceInsert', 'referenceModify', 'referenceRemove') * @param in_callback - The callback to invoke when the operation occurs * @param in_options - Additional user specified options for the * callback and its registration * @returns A handle that can be used to unregister the callback. */ registerOnPath(in_absolutePath: string | Array, in_operations: Array, in_callback: Function, in_options?: IRegisterOnPathOptions): DataBinderHandle; /** * Registers a handler that is called every time a change affects the property at the given path * from the root of the workspace. * * @param in_absolutePath - Path to register the handler for, relative to * the root of the workspace. * @param in_operations - * the operations for which the callback function gets called * (one of 'insert', 'modify', 'remove', 'collectionInsert', 'collectionModify', 'collectionRemove', * 'referenceInsert', 'referenceModify', 'referenceRemove') * @param in_callback - The callback to invoke when the operation occurs * @param in_options - Additional user specified options for the * callback and its registration * @returns A handle that can be used to unregister the callback. * @hidden */ private _internalRegisterOnPath; /** * Attaches this DataBinder to the given Workspace. Any bindings that are registered will be * applied to the current contents of the workspace. Future ChangeSets produced by the Workspace * will be processed and the corresponding data bindings will be created, updated or removed as * appropriate. * * @param propertyTree - The Workspace to bind to. */ attachTo(propertyTree: SharedPropertyTree): void; /** * Blindly build the databindingtree to match the property layout, during the startup, rather than building * it bit by bit based on the changeset. * * This will be removed in favour of a lazy mechanism in the future. * * @hidden */ private _buildDataBindingTree; /** * Detaches from a Workspace if currently bound. All existing data bindings instances will * be destroyed as if the properties had been removed from the workspace. * * If in_unregisterAll is true (the default), all DataBindings are undefined and deactivated. * If false, it will leave them, and when attaching to a new Workspace, the DataBindings will * be applied. * * @param in_unregisterAll if true (the default), all DataBindings are undefined and * deactivated. If false, they remain, and will apply */ detach(in_unregisterAll?: boolean | undefined): void; /** * Helper function to deactivate all bindings of the given binding type (this is a helper to avoid calling destroy() * on all the handles returned by activateDataBinding) * * @param in_bindingType - the binding type to deactivate. * * @private * @hidden */ private _deactivateDataBindings; /** * Helper function to undefine all bindings of the given binding type (this is a helper to avoid calling destroy() on * all the handles returned by defineDataBinding). * * Note that any existing data bindings will remain until the associated activation is deactivated. * * @param iun_bindingType - the binding type to undefine. If none provided, all data bindings * will be removed. * * @hidden */ private _undefineDataBindings; /** * Helper function that will deactivate all bindings of a particular bindingType, and * undefine any DataBindings of that bindingType. * * Note that {@link DataBinder.defineDataBinding} also returns a {@link DataBinderHandle} that can be * used for unregistering DataBindings. * * @param in_bindingType - the binding type for which to unregister. If not provided (the default), all * bindings associated with this DataBinder are affected. * @param in_deactivate - if true (the default), deactivate any activations for this binding type, * created from {@link DataBinder.activateDataBinding} or {@link DataBinder.register} * @param in_undefine - if true (the default), undefine all bindings for this binding type * {@link DataBinder.defineDataBinding} or {@link DataBinder.register} */ unregisterDataBindings(in_bindingType?: string, in_deactivate?: boolean, in_undefine?: boolean): void; /** * Return true if this DataBinder is attached to a Workspace. * * @returns True if the DataBinder is attached to a Workspace. */ isAttached(): boolean; /** * Create the data binding from the provided definition at the given path. * If it already exists, undefined is returned * * @param in_context - the current traversal context * @param in_definition - the binding definition (constructor etc) * @param in_activationInfo - information such as binding type, userData, databinder * shared amongs all instances of the binding of this definition. * * @returns The instantiated binding, unless it already exists * @private * @hidden */ _createBindingFromDefinition(in_context: Utils.TraversalContext, in_definition: ActivationType, in_activationInfo: object): DataBinding | undefined; /** * Internal function to instantiate all the data bindings at the given path * * @param in_context - The traversal context * @param in_path - Path of the property to create the data bindings for * @hidden */ private _createAllBindingsAtPath; /** * Function that is invoked in the post-order traversal, if any data bindings have been created in the pre-order * traversal for this node. It will invoke the corresponding event handlers on the created data bindings * * @param in_context - Traversal context * * @private * @hidden */ _postCreateDataBinding(in_context: Utils.TraversalContext): void; /** * @param in_context - The traversal context * @param in_modificationContext - The modification context * * @hidden */ private _callPathCallbacks; /** * Removes a data binding from the DataBinding tree and invokes the onRemove and onPreRemove handlers for * all child data bindings * * @param in_parentNode - * The parent node of the node to remove * @param in_index - Index to the node to remove * @param in_path - path leading to the parent node * * @hidden */ private _removeDataBindings; /** * Handle a (single) modify while traversing a ChangeSet * * @param in_context - the traversal context * @param in_post - true if called post-order * @private * @hidden */ _handleModify(in_context: Utils.TraversalContext, in_post: boolean): void; /** * Handle a (single) removal while traversing a ChangeSet * * @param in_context - the traversal context * @param in_post - true if called post-order * @param in_tokenizedPathSegments - the tokenized path segments from the last existing * DataBindingTree node * @private * @hidden */ _handleRemove(in_context: Utils.TraversalContext, in_post: boolean, in_tokenizedPathSegments: string | Array): void; /** * Handle a (single) insertion while traversing a ChangeSet * * @param in_context - the traversal context * @param in_post - true if called post-order * @param in_tokenizedPathSegments - the tokenized path segments from the last * existing DataBindingTree node * @param in_propertyContext - Context of the object to insert * @private * @hidden */ _handleInsert(in_context: Utils.TraversalContext, in_post: boolean, in_tokenizedPathSegments: string | Array, in_propertyContext: string): void; /** * Handle a (single) change while traversing a ChangeSet * * @param in_context - the traversal context * @param in_post - true if called post-order * @private * @hidden */ _handleChange(in_context: Utils.TraversalContext, in_post: boolean): void; /** * Pre-order callback for the recursive traversal * * @param in_context - Traversal context * @private * @hidden */ _preTraversalCallBack(in_context: Utils.TraversalContext): void; /** * Post-order callback for the recursive traversal. it's only used to create the actual Data Bindings. * * @param {TraversalContext} in_context - Traversal context * @private * @hidden */ _postTraversalCallBack(in_context: Utils.TraversalContext): void; /** * Traverses a ChangeSet recursively and invokes the callback for each visited property. * * @param in_changeSet - The ChangeSet to process * @private * @hidden */ _traverseChangeSet(in_changeSet: SerializedChangeSet): void; /** * Modify the scene according to the ChangeSet passed in. Traversal is depth first and recursively processes the * change set. * * For each section of the change set either an Data Binding exists (or will exist) or there is no data binding * representation. * If there is (or will be) a data binding, then a ModificationSet is created. This ModificationSet is passed along to * further processing of the change set until such time as it is no longer necessary. After the section of the change * set that created the ModificationSet is done processing, a copy of the ModificationSet is sent to each Data * Binding. * * If there is no data binding representation, the provided ModificationSet is added to and passed on for further * processing. * * @hidden * * @param in_changeSet - ChangeSet describing the modification. * @throws Will throw an error if a traversal is already active. */ private _modifyScene; /** * Do any requests that were queued up for post-changeset processing * * @hidden */ private _postChangesetProcessing; /** * Return the data bindings (if any) that correspond to the given path or property. May be filtered by binding type. * * @param in_pathOrProperty - Absolute path to a data binding or property corresponding * to a data binding * @param in_bindingType - The requested bindingType. If none has been given, all bindings will be * returned * * @returns If no binding type is given then an array of data * bindings (either all in registration order or an empty array if no suitable bindings are present at the given path * or Property). If a binding type is given it's either a single data binding or undefined if no suitable bindings * are present at the given path or Property. */ resolve(in_pathOrProperty: string | BaseProperty, in_bindingType?: string): T | T[] | undefined; /** * Return the removed Data Binding (if any) that correspond to the given path and type. * @param in_path - absolute path to an data binding * @param in_bindingType - The requested bindingType * @returns A data binding (of the given * type) which may be undefined if no suitable data binding is present at the given path. * @package * @private * @hidden */ _resolveRemovedDataBindingByType(in_path: string, in_bindingType: string): DataBinding | undefined; /** * In callbacks such as registerOnPath, with DataBinder or DataBindings, the callbacks are being done * while processing the current change set. Currently, is is prohibited to do modifications to * the PropertyTree during one such callback. * * If a change to the PropertyTree is required in a callback, clients can use the ```requestChangesetPostProcessing``` * function to call the provided callback to be called after the current change set is processed. * * There is no guarantee on the order the callbacks will be called in. * * @param in_callback - A post creation callback function for each data binding called * after the ChangeSet has been processed * @param in_context - Optional value to be passed as * the ```this``` parameter to the target function when the bound function is called */ requestChangesetPostProcessing(in_callback: Function, in_context?: any): void; /** * Return the Workspace the DataBinder is currently attached to, or undefined if not attached. * * @returns The Workspace the DataBinder is attached to. */ getPropertyTree(): SharedPropertyTree | undefined; /** * Register a generator to be used to build a new runtime representation for the given bindingType / typeID. * The function will be called lazily based on calls to {@link DataBinder.getRepresentation}. * By design, the generator functions can themselves call getRepresentation for other properties in the system, and * their generators will be recursively built. The DataBinder will detect cycles in these inter-dependencies but * does not directly resolve them. * It is possible to define runtime representations for multiple levels of an inherited type. When * {@link DataBinder.getRepresentation} is called for a property, the most specialized runtime represenation * registered will be called. Care should be taken by the user to ensure all runtime representations are defined * before they begin to be built. * * @example * * ```javascript * // Register a generator for runtime representations for the Dog Property * myDataBinder.defineRepresentation('PETSTORE', 'Types:Dog-1.0.0', (property) => new DogRepresentation()); * * // Get a ShartedProperty tree and insert a new property * const propertyTree = getSharedPropertyTree(); * myDataBinder.attachTo(propertyTree); * * propertyTree.root.insert('Fido', PropertyFactory.create('Types:Dog-1.0.0', 'single')); * * // Request the runtime representation associated with the property * const fido = myDataBinder.getRepresentation(workspace.root.get('Fido'), 'PETSTORE'); * console.assert(fido instanceof DogRepresentation); * ``` * * @param bindingType - The binding type to associate this runtime representation with. Allows multiple * runtime representations to be built for the same property. * @param typeID - The type id for which to generate this runtime representation. Care must be taken when * defining types that inherit from each other; all types should be registered before the runtime representations * begin to be created. * @param generator - Callback to create a new runtime representation for the provided * property. The bindingType, and the userData specified here in the options are provided to the callback function. * Note, if the creation needs to be broken into two states, see the options.initializer option. * @param options - Options block * * @returns A handle to permit unregistering of the runtime representation. * * @throws If there is already runtime representation associated with the provided bindingType/typeID. */ defineRepresentation(bindingType: string, typeID: string, generator: representationGenerator, options?: IDefineRepresentationOptions | undefined): DataBinderHandle; /** * Unregister and destroy all the runtime representations associated with the given handle * * @param in_handle - the handle for this runtime representation definition * @param in_representationInfo - the runtime representation information * * @private * @hidden */ _undefineRepresentation(in_handle: DataBinderHandle, in_representationInfo: any): void; /** * Recursively destroy all the runtime representations currently instantiated * * @private * @hidden */ _recursivelyDestroyAllRepresentations(): void; /** * Destroy all the instances of representations that are on this node * * @param in_node - the node we want to clear the representations from * * @private * @hidden */ _destroyAllRepresentationsAtNode(in_node: DataBindingTree): void; /** * Return the representation associated to the given property, for the particular binding type. * If the representation has not been built before, it will be created on the fly. * * NOTE/WARNING: If this property is inside a repository reference, this function can fail. In that case, * please use {@link DataBinder.getRepresentationAtPath} and use an explicit path. * * @param property - The property for which we want the runtime representation * @param bindingType - The binding type of the runtime representation * * @returns The initialized runtime representation, or undefined if there is none registered * * @throws If there is a cycle in the generators for the creation of the runtime representations. Avoid the cyclic * calls, or use the 'initializer' option when specifying the generator in {@link DataBinder.defineRepresentation} * @throws If the generator or a recursively-used generator fails to return a runtime representation when called. * @throws If not connected to a workspace * @throws If the property is not in the workspace the DataBinder is attached to. * @throws If the given property is undefined */ getRepresentation(property: BaseProperty, bindingType: string): T | undefined; /** * Return the representation associated to the given path, for the particular binding type. * If the representation has not been built before, it will be created on the fly. * * @param path - The absolute path to the property for which we want the runtime representation. * @param bindingType - The binding type of the runtime representation. * * @returns the initialized runtime representation, or undefined if there is none registered * * @throws If there is a cycle in the generators for the creation of the runtime representations. Avoid the cyclic * calls, or use the 'initializer' option when specifying the generator in {@link DataBinder.defineRepresentation} * @throws If the generator or a recursively-used generator fails to return a runtime representation when called. * @throws If not connected to a workspace * @throws If the property does not exist at the provided path */ getRepresentationAtPath(path: string, bindingType: string): T | undefined; /** * Internal function for getting the representation given the property and the path to the property. * * @param path - the path to the property. * @param property - the property for which we want the representation. * @param bindingType - the binding type we want the representation. * * @returns the initialized runtime representation, or undefined if there is none registered * * @private * @hidden */ _getRepresentationAtPathInternal(path: string, property: BaseProperty, bindingType: string): any | undefined; /** * Create an DataBinding tree node and an associated value for the given property, if not already there. * * @param in_property - the property for which we want to instantiate the associated node * @param in_tokenizedPath - the path to the property * * @returns The created node, guaranteed to also have a value * * @private * @hidden */ _instantiateNodeAndValueForProperty(in_property: BaseProperty, in_tokenizedPath: Array): NodeType; /** * Permits associating an existing runtime representation with a property. * * Typically, representations are created lazily when {@link DataBinder.getRepresentation} is called. This function * provides applications the ability to associate an existing runtime representation with a property/bindingType * pair. * * NOTE: The representation is expected to be of a type that is compatible with the maker/destroyers * specificed using {@link DataBinder.defineRepresentation}. * If the defined representation has a destroyer associated with it (see {@link DataBinder.defineRepresentation}), * then if this property is removed, the destroyer will be called on it. * * It is not permitted to associate a representation with a property/bindingType pair that already has * a representation associated with it. Users should be aware that if getRepresentation is done by * another subsystem for a property P, a representation will be lazily instantiated, and therefore * associateRepresentation for property P will fail. * * @param in_property - Property with which we want to associate a representation. * @param in_bindingType - binding type of the representation. This allows multiple representations * to be associated with a single property. * @param in_representation - the representation to associate with this property. * * @throws If not attached to a workspace * @throws If the provided property is not part of the workspace attached to the DataBinder * @throws If the provided property/bindingType pair does not have a runtime representation defined for it. * @throws If the provided property/bindingType pair already has a representation associated with it * @throws If the provided property/bindingType pair has a stateless runtime representation defined for it. */ associateRepresentation(in_property: BaseProperty, in_bindingType: string, in_representation: any): void; /** * Taking class hiearchy into account, find the most appropriate runtime representation to instantiate * for this property. * * @param in_property - the property for which we want to create the runtime representation * @param in_bindingType - the binding type we are interested in * * @returns he runtime data representation information * * @private * @hidden */ _getAppropriateRepresentationInfo(in_property: BaseProperty, in_bindingType: string): any | undefined; /** * Destroy the runtime representation, calling the user callback if necessary. * * @param in_representation - the runtime representation * @param in_representationInfo - the information about creating/destroying this runtime representation * * @private * @hidden */ _destroyRepresentation(in_representation: any, in_representationInfo: any): void; /** * Create the runtime representation for this property * * @param in_tokenizedPath - the tokenized path to this property * @param in_property - the property the runtime representation is associated with * @param in_representationInfo - the runtime representation information for building/destroying * the representation * @param in_key - key to use for querying the currently building stateless representations map * * @returns The created runtime representation * * @private * @hidden */ _instantiateRepresentation(in_tokenizedPath: Array, in_property: BaseProperty, in_representationInfo: any, in_key?: string | undefined): object; /** * Convenience function for undefining all runtime representations associated with the given binding type. This will * cause any runtime representations that were generated to have their destroyer callbacks called. * Note; this will also invalidate any handles returned from {@link DataBinder.defineRepresentation}. * * @param in_bindingType - the binding type to undefine, if not provided, all representations will be * undefined */ undefineAllRepresentations(in_bindingType?: string): void; /** * Return the unique id for the current/last changeset to be processed. * This id is guaranteed to change for every changeset that enters. * * @returns A unique changeset id, greater than or equal to zero. * * @hidden */ getCurrentChangeSetId(): number; /** * A unique key per running application; each instance of the databinder will have a different Id. * * @returns The id of this DataBinder instance. */ getDataBinderId(): number; /** * Reset internal debug counters (used for testing) * @hidden */ _resetDebugCounters(): void; } //# sourceMappingURL=dataBinder.d.ts.map