[This is preliminary documentation and is subject to change.]
The Parcel type exposes the following members.Constructors
Name | Description | |
---|---|---|
![]() | Parcel |
Used for serialization
|
![]() | Parcel(Object) |
This ctor is never public, used with __ctor__injectID
|
![]() | Parcel(GDID, Object) |
Called when creating new Parcel instances by the original author.
The new instance is in 'ParcelState.Creating' state
|
![]() | Parcel(GDID, Object, IReplicationVersionInfo) |
Called by device to load parcel from storage.
The new instance is in 'ParcelState.Sealed' state.
Business logic devs - do not call
|
Methods
Name | Description | |
---|---|---|
![]() | __ctor__injectID |
Internal framework method, developers: never call
|
![]() | DeepClone |
Duplicates this parcel by doing a complete deep-clone of its state via serialization.
This method is useful for making copies of the same parcel for different threads as it is thread-safe while no other thread mutates the instance,
however Parcel instances are NOT THREAD-SAFE for parallel changes.
The existing parcel MUST be SEALED (otherwise it can not be serialized).
This method is also used before a call to Open() if parcel needs to be "un-opened" the cloned instance may be reverted to
|
![]() | Destructor |
Override this method to do actual destructor work
(Inherited from DisposableObject.) |
![]() | Dispose |
Deterministically disposes object. DO NOT OVERRIDE this method, override Destructor() instead
(Inherited from DisposableObject.) |
![]() | DoMerge |
Override to merge other parcels into this one. Return true if merge changed the payload. See Merge().
This implementation throws an exception
|
![]() | DoOpen |
Override to perform actions when parcel is unsealed (opened) for modification
|
![]() | DoSeal |
Override to seal the parcel instance, i.e. generate some calculated fields.
The version information is already generated by the time this method is called
|
![]() | DoValidate |
Override to perform parcel/payload validation after modification. Add validation exceptions into m_ValidationExceptions field.
Use bank for cross-checks (i.e. may run queries to check consistency)
|
![]() | EnsureObjectNotDisposed |
Checks to see whether object dispose started or has already been disposed and throws an exception if Dispose() was called
(Inherited from DisposableObject.) |
![]() | Equals |
Tests for parcel equality based on the same type and GDID value
(Overrides ![]() |
![]() | Finalize | (Inherited from DisposableObject.) |
![]() | GetDistributedStableHash | |
![]() | GetHashCode |
Generates hash code based on parcel type and GDID value
(Overrides ![]() |
![]() ![]() | GetParcelCacheTableName |
Obtains parcel cache name from either it's associated DataParcelAttribute or
if not defined, from parcel type full name
|
![]() | ![]() | Gets the (Inherited from ![]() ![]() |
![]() | ![]() | Creates a shallow copy of the current (Inherited from ![]() ![]() |
![]() | Merge |
Merges other parcel instances into this one.
A parcel type may support merging (when DataParcel attribute SupportsMerge is set to true) of data from other parcels/versions into this instance.
This parcel must not be sealed as merge may change the payload in which case TRUE is returned. The parcel needs to be sealed again after the change.
If a call to this method returns false, then nothing was changed as this instance already contains the latest data/could not be merged.
Merging is used for version conflict resolution: servers check if the type of the updated parcel instance SupportsMerge, then if it does, Opens parcel
and calls this method passing other versions in question to this method. The framework does not impose a limit on the supplied parcel types, however
most of the parcel types support merge only with the same-typed parcel instances.
IMPORTANT: The ordering of parcel versions is not guaranteed.
|
![]() | Open |
Opens parcel for modification. Parcel must be in the Sealed state for this call and must not be ReadOnly.
Once open for modification, a parcel can not be "UnOpened", only Seal()-ed. This is because there is no way to track
whether some part of payload object has changed by the calling code. Use DeepClone() before calling Open to retain a copy of Sealed parcel
to revert to the cloned instance instead
|
![]() | Seal |
Seal parcel after modification
May call this method on parcels in either Creating or Modifying states.
Bank is used to create the ReplicationVersionInfo which is depends on store/bank implementation.
Parcels can replicate only within stores/technologies that have sealed them
|
![]() | ToString | (Overrides ![]() |
![]() | Validate |
Performs validation of the data. Does not throw but populates validation exceptions if data is not valid.
Bank context may be used to run sub-queries during consistency/crosschecks
May call this method on parcels in either Creating or Modifying states
|
Extension Methods
Fields
Name | Description | |
---|---|---|
![]() ![]() | DEFAULT_REPLICATION_PRIORITY |
Default priority of replication
|
![]() | m_ValidationExceptions | |
![]() ![]() | STANDARD_KNOWN_SERIALIZER_TYPES |
Defines well-known frequently used types for slim serializer compression
|
Properties
Name | Description | |
---|---|---|
![]() | CacheAbsoluteExpirationUTC |
Implements IParcelCachePolicy contract.
The default implementation returns null.
Override to supply a different absolute cache expiration UTC timestamp for this parcel
that may depend on particular parcel payload state (i.e. field values).
|
![]() | CachePriority |
Implements IParcelCachePolicy contract.
The default implementation returns null.
Override to supply a relative cache priority of this parcel
that may depend on particular parcel payload state (i.e. field values).
|
![]() | CacheReadMaxAgeSec |
Implements IParcelCachePolicy contract.
The default implementation returns null.
Override to supply a value for maximum validity span of cached parcel
that may depend on particular parcel payload state (i.e. field values).
This property may be used to obtain a value before parcel is re-read from the store
|
![]() | CacheWriteMaxAgeSec |
Implements IParcelCachePolicy contract.
The default implementation returns null.
Override to supply a value for maximum length of this isntance stay in cache
that may depend on particular parcel payload state (i.e. field values)
|
![]() | Disposed |
Indicates whether this object was already disposed - the Dispose() has finished
(Inherited from DisposableObject.) |
![]() | DisposeStarted |
Indicates whether this object Dispose() has been called and dispose started but not finished yet
(Inherited from DisposableObject.) |
![]() | EffectiveCachePolicy |
Returns effective cache policy the one that is calculated from attribute and overidden by the instance
|
![]() | GDID |
Returns GDID for data that this parcel represents
|
![]() | MetadataAttribute |
Returns DataParcelAttribute that describes this parcel. Every parcel MUST be decorated by the DataParcel attribute
|
![]() | NewlySealed |
Returns true when parcel was just sealed after a call to Open or .ctor/create.
Datastore may check this flag and disallow saving of parcel instances that have not changed
|
![]() | Payload |
Returns payload of this parcel. This may be null for deleted parcels (VersionDeleted).
WARNING!!! Although parcels do not allow to set Payload property if they are sealed, one can still mutate/modify the payload object graph
even on a sealed parcel instance, i.e. one may write:
mySealedParcel.Payload.DueDates.Add(DateTime.Now) (given DueDates of type List(DateTime)) |
![]() | ReadOnly |
Indicates whether the data may be altered.
ReadOnly parcels can not be Opened after that have been Sealed by their creator
|
![]() | ReplicationPriority |
Returns replication priority, override to make replication priority dependent on instance, i.e. a user profile data for
a celebrity user may need to have higher replication rate. The lower value indicates the higher priority
|
![]() | ReplicationVersionInfo |
Implements IReplicatable interface
|
![]() | ShardingID |
Returns the ShardingID used for sharding, default implementation returns this parcel type and GDID.
Override to return another sharding key, i.e. a social comment msg may use parent item (that the msg relates to) ID
as the shard key so msgs are co-located with related items. Use CompositeShardingID to return multiple values.
IMPORTANT!!! ShardingID must return an immutable value, the one that CAN NOT be changed during parcel payload life
|
![]() | ShardingPointer |
Returns the ShardingPointer(type:ID) used for sharding, default implementation returns this parcel type and GDID.
Override ShardingID property to return another sharding key, i.e. a social comment msg may use parent item (that the msg relates to) ID
as the shard key so msgs are co-located with related items. Use CompositeShardingID to return multiple values.
IMPORTANT!!! ShardingPointer must return an immutable value, the one that CAN NOT be changed during parcel payload life
|
![]() | State |
Returns the state of the parcel: Creating|Modifying|Sealed
|
![]() | ValidationExceptions |
Returns validation exceptions - populated by a call to Validate
|
Explicit Interface Implementations
Name | Description | |
---|---|---|
![]() ![]() | ICachePolicy CacheTableName |
Implements IParcelCachePolicy contract.
The implementation returns null for parcel.
|
See Also