SharedObjectCore Class

Base class from which all shared objects derive.

This API is provided for existing users, but is not recommended for new users.

To use, import via @fluidframework/shared-object-base/legacy.

For more information about our API support guarantees, see here.

Signature

export declare abstract class SharedObjectCore<TEvent extends ISharedObjectEvents = ISharedObjectEvents> extends EventEmitterWithErrorHandling<TEvent> implements ISharedObject<TEvent>

Extends: EventEmitterWithErrorHandling<TEvent>

Implements: ISharedObject<TEvent>

Type Parameters

Parameter	Constraint	Default	Description
TEvent	ISharedObjectEvents	ISharedObjectEvents

Remarks

This class implements common behaviors that implementations of ISharedObject may want to reuse. Even more such behaviors are implemented in the SharedObject class. \

Constructors

Constructor	Alerts	Description
(constructor)(id, runtime, attributes)	Beta	Constructs a new instance of the SharedObjectCore class

Properties

Property	Alerts	Modifiers	Type	Description
attributes	Beta	readonly	IChannelAttributes	The attributes of the Shared Object.
connected	Beta	readonly	boolean	Gets the connection state
deltaManager	Beta	readonly	IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>	Accessor for this.runtime's deltaManager as a @fluidframework/container-definitions/internal#IDeltaManager
handle	Beta	readonly	IFluidHandleInternal	The handle referring to this SharedObject
id	Beta		string	The ID of the shared object.
IFluidLoadable	Beta	readonly	this
logger	Beta	readonly	ITelemetryLoggerExt	Telemetry logger for the shared object
runtime	Beta		IFluidDataStoreRuntime	The runtime instance that contains the Shared Object.
serializer	Beta	readonly	IFluidSerializer	The serializer to serialize / parse handles.

Methods

Method	Alerts	Modifiers	Return Type	Description
applyStashedOp(content)	Beta		void	Apply changes from the provided op content just as if a local client has made the change, including submitting the op. Used when rehydrating an attached container with pending changes. The rehydration process replays all remote ops and applies stashed ops after the remote op with a sequence number that matches that of the stashed op is applied. This ensures stashed ops are applied at the same state they were originally created. It is possible that stashed ops have been sent in the past, and will be found when the shared object catches up with remotes ops. So this prepares the SharedObject for seeing potentially seeing the ACK. If no matching remote op is found, all the applied stashed ops will go through the normal resubmit flow upon reconnection, which allows the dds to rebase them to the latest state, and then resubmit them.
bindToContext()	Beta		void	Binds the given shared object to its containing data store runtime, causing it to attach once the runtime attaches.
connect(services)	Beta		void	Enables the channel to send and receive ops.
didAttach()	Beta		void	Allows the distributive data type the ability to perform custom processing once an attach has happened. Also called after non-local data type get loaded.
dirty()	Beta		void	Marks this object as dirty so that it is part of the next summary. It is called by a SharedSummaryBlock that want to be part of summary but does not generate ops.
emit(event, args)	Beta		boolean	Emit an event. This function is only intended for use by DDS classes that extend SharedObject/SharedObjectCore, specifically to emit events that are part of the public interface of the DDS (i.e. those that can have listeners attached to them by the consumers of the DDS). It should not be called from outside the class or to emit events which are only internal to the DDS. Support for calling it from outside the DDS instance might be removed in the future.
getAttachSummary(fullTree, trackState, telemetryContext)	Beta		ISummaryTreeWithStats	Generates summary of the channel synchronously. It is called when an attach message for a local channel is generated. In other words, when the channel is being attached to make it visible to other clients.
getGCData(fullGC)	Beta		IGarbageCollectionData	Returns the GC data for this channel. It contains a list of GC nodes that contains references to other GC nodes.
initializeLocal()	Beta		void	Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.
initializeLocalCore()	Beta		void	Allows the distributed data type to perform custom local loading.
isAttached()	Beta		boolean	Checks if the channel is attached to storage.
load(services)	Beta		Promise<void>	A shared object, after construction, can either be loaded in the case that it is already part of a shared document. Or later attached if it is being newly added.
loadCore(services)	Beta		Promise<void>	Allows the distributed data type to perform custom loading
newAckBasedPromise(executor)	Beta		Promise<T>	Promises that are waiting for an ack from the server before resolving should use this instead of new Promise. It ensures that if something changes that will interrupt that ack (e.g. the FluidDataStoreRuntime disposes), the Promise will reject. If runtime is disposed when this call is made, executor is not run and promise is rejected right away.
onConnect()	Beta		void	Called when the object has fully connected to the delta stream Default implementation for DDS, override if different behavior is required.
onDisconnect()	Beta		void	Called when the object has disconnected from the delta stream.
processCore(message, local, localOpMetadata)	Deprecated, Beta		void	Derived classes must override this to do custom processing on a remote message.
processMessagesCore(messagesCollection)	Beta	optional	void	Process a 'bunch' of messages for this shared object.
reSubmitCore(content, localOpMetadata)	Beta		void	Called when a message has to be resubmitted. This typically happens after a reconnection for unacked messages. The default implementation here is to resubmit the same message. The client can override if different behavior is required. It can choose to resubmit the same message, submit different / multiple messages or not submit anything at all.
reSubmitSquashed(content, localOpMetadata)	Beta		void	Called when a message has to be resubmitted but its content should be "squashed" if any subsequent pending changes override the content in the fashion described on reSubmit(message, localOpMetadata, squash).
rollback(content, localOpMetadata)	Beta		void	Revert an op
submitLocalMessage(content, localOpMetadata)	Beta		void	Submits a message by the local client to the runtime.
summarize(fullTree, trackState, telemetryContext)	Beta		Promise<ISummaryTreeWithStats>	Generates summary of the channel asynchronously. This should not be called where the channel can be modified while summarization is in progress.

Constructor Details

(constructor)

Constructs a new instance of the SharedObjectCore class

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

constructor(
    id: string, 
    runtime: IFluidDataStoreRuntime, 
    attributes: IChannelAttributes);

Parameters

Parameter	Type	Description
id	string
runtime	IFluidDataStoreRuntime
attributes	IChannelAttributes

Property Details

attributes

The attributes of the Shared Object.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly attributes: IChannelAttributes;

Type: IChannelAttributes

connected

Gets the connection state

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get connected(): boolean;

Type: boolean

deltaManager

Accessor for this.runtime's deltaManager as a @fluidframework/container-definitions/internal#IDeltaManager

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected get deltaManager(): IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>;

Type: IDeltaManager<ISequencedDocumentMessage, IDocumentMessage>

handle

The handle referring to this SharedObject

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

readonly handle: IFluidHandleInternal;

Type: IFluidHandleInternal

id

The ID of the shared object.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

id: string;

Type: string

IFluidLoadable

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

get IFluidLoadable(): this;

Type: this

logger

Telemetry logger for the shared object

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected readonly logger: ITelemetryLoggerExt;

Type: ITelemetryLoggerExt

runtime

The runtime instance that contains the Shared Object.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected runtime: IFluidDataStoreRuntime;

Type: IFluidDataStoreRuntime

serializer

The serializer to serialize / parse handles.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected abstract get serializer(): IFluidSerializer;

Type: IFluidSerializer

Method Details

applyStashedOp

Apply changes from the provided op content just as if a local client has made the change, including submitting the op. Used when rehydrating an attached container with pending changes. The rehydration process replays all remote ops and applies stashed ops after the remote op with a sequence number that matches that of the stashed op is applied. This ensures stashed ops are applied at the same state they were originally created.

It is possible that stashed ops have been sent in the past, and will be found when the shared object catches up with remotes ops. So this prepares the SharedObject for seeing potentially seeing the ACK. If no matching remote op is found, all the applied stashed ops will go through the normal resubmit flow upon reconnection, which allows the dds to rebase them to the latest state, and then resubmit them.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected abstract applyStashedOp(content: unknown): void;

Parameters

Parameter	Type	Description
content	unknown	Contents of a stashed op.

bindToContext

Binds the given shared object to its containing data store runtime, causing it to attach once the runtime attaches.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

bindToContext(): void;

connect

Enables the channel to send and receive ops.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

connect(services: IChannelServices): void;

Parameters

Parameter	Type	Description
services	IChannelServices	The services to connect to.

didAttach

Allows the distributive data type the ability to perform custom processing once an attach has happened. Also called after non-local data type get loaded.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected didAttach(): void;

dirty

Marks this object as dirty so that it is part of the next summary. It is called by a SharedSummaryBlock that want to be part of summary but does not generate ops.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected dirty(): void;

emit

Emit an event. This function is only intended for use by DDS classes that extend SharedObject/SharedObjectCore, specifically to emit events that are part of the public interface of the DDS (i.e. those that can have listeners attached to them by the consumers of the DDS). It should not be called from outside the class or to emit events which are only internal to the DDS. Support for calling it from outside the DDS instance might be removed in the future.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

emit(event: EventEmitterEventType, ...args: any[]): boolean;

Parameters

Parameter	Type	Description
event	EventEmitterEventType	The event to emit.
args	any[]	Arguments to pass to the event listeners.

Returns

true if the event had listeners, false otherwise.

Return type: boolean

getAttachSummary

Generates summary of the channel synchronously. It is called when an attach message for a local channel is generated. In other words, when the channel is being attached to make it visible to other clients.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

abstract getAttachSummary(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): ISummaryTreeWithStats;

Remarks

Note: Since the Attach Summary is generated for local channels when making them visible to remote clients, they don't have any previous summaries to compare against. For this reason, the attach summary cannot contain summary handles (paths to sub-trees or blobs). It can, however, contain @fluidframework/protocol-definitions#ISummaryAttachment (handles to blobs uploaded async via the blob manager).

Parameters

Parameter	Modifiers	Type	Description
fullTree	optional	boolean	A flag indicating whether the attempt should generate a full summary tree without any handles for unchanged subtrees. Default: false
trackState	optional	boolean	An optimization for tracking state of objects across summaries. If the state of an object did not change since last successful summary, an @fluidframework/protocol-definitions#ISummaryHandle can be used instead of re-summarizing it. If this is false, the expectation is that you should never send an ISummaryHandle, since you are not expected to track state. Note: The goal is to remove the trackState and automatically decided whether the handles will be used or not: https://github.com/microsoft/FluidFramework/issues/10455 Default: false
telemetryContext	optional	ITelemetryContext	See ITelemetryContext.

Returns

A summary capturing the current state of the channel.

Return type: ISummaryTreeWithStats

getGCData

Returns the GC data for this channel. It contains a list of GC nodes that contains references to other GC nodes.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

abstract getGCData(fullGC?: boolean): IGarbageCollectionData;

Parameters

Parameter	Modifiers	Type	Description
fullGC	optional	boolean	true to bypass optimizations and force full generation of GC data.

Returns

Return type: IGarbageCollectionData

initializeLocal

Initializes the object as a local, non-shared object. This object can become shared after it is attached to the document.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

initializeLocal(): void;

initializeLocalCore

Allows the distributed data type to perform custom local loading.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected initializeLocalCore(): void;

isAttached

Checks if the channel is attached to storage.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

isAttached(): boolean;

Returns

True iff the channel is attached.

Return type: boolean

load

A shared object, after construction, can either be loaded in the case that it is already part of a shared document. Or later attached if it is being newly added.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

load(services: IChannelServices): Promise<void>;

Parameters

Parameter	Type	Description
services	IChannelServices	Services used by the shared object

Returns

Return type: Promise<void>

loadCore

Allows the distributed data type to perform custom loading

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected abstract loadCore(services: IChannelStorageService): Promise<void>;

Parameters

Parameter	Type	Description
services	IChannelStorageService	Storage used by the shared object

Returns

Return type: Promise<void>

newAckBasedPromise

Promises that are waiting for an ack from the server before resolving should use this instead of new Promise. It ensures that if something changes that will interrupt that ack (e.g. the FluidDataStoreRuntime disposes), the Promise will reject. If runtime is disposed when this call is made, executor is not run and promise is rejected right away.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected newAckBasedPromise<T>(executor: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: unknown) => void) => void): Promise<T>;

Type Parameters

Parameter	Description
T

Parameters

Parameter	Type	Description
executor	(resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: unknown) => void) => void

Returns

Return type: Promise<T>

onConnect

Called when the object has fully connected to the delta stream Default implementation for DDS, override if different behavior is required.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected onConnect(): void;

onDisconnect

Called when the object has disconnected from the delta stream.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected abstract onDisconnect(): void;

processCore

Derived classes must override this to do custom processing on a remote message.

This API is deprecated and will be removed in a future release.

Replaced by processMessagesCore(messagesCollection).

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected abstract processCore(message: ISequencedDocumentMessage, local: boolean, localOpMetadata: unknown): void;

Parameters

Parameter	Type	Description
message	ISequencedDocumentMessage	The message to process
local	boolean	True if the shared object is local
localOpMetadata	unknown	For local client messages, this is the metadata that was submitted with the message. For messages from a remote client, this will be undefined.

processMessagesCore

Process a 'bunch' of messages for this shared object.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected processMessagesCore?(messagesCollection: IRuntimeMessageCollection): void;

Remarks

A 'bunch' is a group of messages that have the following properties: - They are all part of the same grouped batch, which entails: - They are contiguous in sequencing order. - They are all from the same client. - They are all based on the same reference sequence number. - They are not interleaved with messages from other clients. - They are not interleaved with messages from other DDS in the container. Derived classes should override this if they need to do custom processing on a 'bunch' of remote messages.

Parameters

Parameter	Type	Description
messagesCollection	IRuntimeMessageCollection

reSubmitCore

Called when a message has to be resubmitted. This typically happens after a reconnection for unacked messages. The default implementation here is to resubmit the same message. The client can override if different behavior is required. It can choose to resubmit the same message, submit different / multiple messages or not submit anything at all.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected reSubmitCore(content: unknown, localOpMetadata: unknown): void;

Parameters

Parameter	Type	Description
content	unknown	The content of the original message.
localOpMetadata	unknown	The local metadata associated with the original message.

reSubmitSquashed

Called when a message has to be resubmitted but its content should be "squashed" if any subsequent pending changes override the content in the fashion described on reSubmit(message, localOpMetadata, squash).

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected reSubmitSquashed(content: unknown, localOpMetadata: unknown): void;

Parameters

Parameter	Type	Description
content	unknown	The content of the original message.
localOpMetadata	unknown	The local metadata associated with the original message.

rollback

Revert an op

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected rollback(content: unknown, localOpMetadata: unknown): void;

Parameters

Parameter	Type	Description
content	unknown
localOpMetadata	unknown

submitLocalMessage

Submits a message by the local client to the runtime.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

protected submitLocalMessage(content: unknown, localOpMetadata?: unknown): void;

Parameters

Parameter	Modifiers	Type	Description
content		unknown	Content of the message. Note: handles contained in the message object should not be encoded in any way
localOpMetadata	optional	unknown	The local metadata associated with the message. This is kept locally by the runtime and not sent to the server. This will be sent back when this message is received back from the server. This is also sent if we are asked to resubmit the message.

summarize

Generates summary of the channel asynchronously. This should not be called where the channel can be modified while summarization is in progress.

This API is provided for existing users, but is not recommended for new users.

For more information about our API support guarantees, see here.

Signature

abstract summarize(fullTree?: boolean, trackState?: boolean, telemetryContext?: ITelemetryContext): Promise<ISummaryTreeWithStats>;

Parameters

Parameter	Modifiers	Type	Description
fullTree	optional	boolean	flag indicating whether the attempt should generate a full summary tree without any handles for unchanged subtrees. It should only be set to true when generating a summary from the entire container. Default: false
trackState	optional	boolean	An optimization for tracking state of objects across summaries. If the state of an object did not change since last successful summary, an @fluidframework/protocol-definitions#ISummaryHandle can be used instead of re-summarizing it. If this is false, the expectation is that you should never send an ISummaryHandle, since you are not expected to track state. Default: false Note: The goal is to remove the trackState and automatically decided whether the handles will be used or not: https://github.com/microsoft/FluidFramework/issues/10455
telemetryContext	optional	ITelemetryContext	See ITelemetryContext.

Returns

A summary capturing the current state of the channel.

Return type: Promise<ISummaryTreeWithStats>