Class Parcel

Describes a data parcel - a piece of logically-grouped data that gets fetched from/comitted into a distributed backend system. Parcels represent an atomic unit of change, a changeset that gets replicated between failover hosts. Every parcel has a Payload property that stores business data of interest that the parcel contains. This class is not thread-safe. Use DeepClone() to create 100% copies for working in multiple threads. This particular class serves as a very base for all Parcel implementations

Inheritance
System.Object
DisposableObject
Parcel
Parcel<TPayload>
Inherited Members
System.Object.Equals(System.Object, System.Object)
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: NFX.DataAccess.Distributed
Assembly: NFX.dll
Syntax
[Serializable]
public abstract class Parcel : DisposableObject, IDisposable, IReplicatable, ICachePolicy, IDistributedStableHashProvider, IShardingPointerProvider

Constructors

Parcel()

Used for serialization

Declaration
protected Parcel()

Parcel(GDID, Object)

Called when creating new Parcel instances by the original author. The new instance is in 'ParcelState.Creating' state

Declaration
protected Parcel(GDID id, object payload)
Parameters
Type Name Description
GDID id
System.Object payload

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

Declaration
protected Parcel(GDID id, object payload, IReplicationVersionInfo versInfo)
Parameters
Type Name Description
GDID id
System.Object payload
IReplicationVersionInfo versInfo

Parcel(Object)

This ctor is never public, used with __ctor__injectID

Declaration
protected Parcel(object payload)
Parameters
Type Name Description
System.Object payload

Fields

DEFAULT_REPLICATION_PRIORITY

Default priority of replication

Declaration
public static int DEFAULT_REPLICATION_PRIORITY
Field Value
Type Description
System.Int32

m_ValidationExceptions

Declaration
[NonSerialized]
protected List<Exception> m_ValidationExceptions
Field Value
Type Description
System.Collections.Generic.List<System.Exception>

STANDARD_KNOWN_SERIALIZER_TYPES

Defines well-known frequently used types for slim serializer compression

Declaration
public static readonly TypeRegistry STANDARD_KNOWN_SERIALIZER_TYPES
Field Value
Type Description
TypeRegistry

Properties

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).

Declaration
public DateTime? CacheAbsoluteExpirationUTC { get; }
Property Value
Type Description
System.Nullable<System.DateTime>

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).

Declaration
public virtual int ? CachePriority { get; }
Property Value
Type Description
System.Nullable<System.Int32>

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

Declaration
public virtual int ? CacheReadMaxAgeSec { get; }
Property Value
Type Description
System.Nullable<System.Int32>

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)

Declaration
public virtual int ? CacheWriteMaxAgeSec { get; }
Property Value
Type Description
System.Nullable<System.Int32>

EffectiveCachePolicy

Returns effective cache policy the one that is calculated from attribute and overidden by the instance

Declaration
public ICachePolicy EffectiveCachePolicy { get; }
Property Value
Type Description
ICachePolicy

GDID

Returns GDID for data that this parcel represents

Declaration
public GDID GDID { get; }
Property Value
Type Description
GDID

MetadataAttribute

Returns DataParcelAttribute that describes this parcel. Every parcel MUST be decorated by the DataParcel attribute

Declaration
public DataParcelAttribute MetadataAttribute { get; }
Property Value
Type Description
DataParcelAttribute

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

Declaration
public bool NewlySealed { get; }
Property Value
Type Description
System.Boolean

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))
.

This case is considered to be a bug in the calling-code. The framework has no way of preventing such an inadvertent behavior as there is no way to intercept a mutation via transitive or direct references/functors in an object graph referenced by Payload property because payload type does not impose (and should not) any constraints on what can be a payload. In Aum language we will use static type checker that will detect possible property access via Payload BEFORE calling Open()

Declaration
public object Payload { get; }
Property Value
Type Description
System.Object

ReadOnly

Indicates whether the data may be altered. ReadOnly parcels can not be Opened after that have been Sealed by their creator

Declaration
public abstract bool ReadOnly { get; }
Property Value
Type Description
System.Boolean

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

Declaration
public virtual int ReplicationPriority { get; }
Property Value
Type Description
System.Int32

ReplicationVersionInfo

Implements IReplicatable interface

Declaration
public IReplicationVersionInfo ReplicationVersionInfo { get; }
Property Value
Type Description
IReplicationVersionInfo

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

Declaration
public virtual object ShardingID { get; }
Property Value
Type Description
System.Object

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

Declaration
public ShardingPointer ShardingPointer { get; }
Property Value
Type Description
ShardingPointer

State

Returns the state of the parcel: Creating|Modifying|Sealed

Declaration
public ParcelState State { get; }
Property Value
Type Description
ParcelState

ValidationExceptions

Returns validation exceptions - populated by a call to Validate

Declaration
public IEnumerable<Exception> ValidationExceptions { get; }
Property Value
Type Description
System.Collections.Generic.IEnumerable<System.Exception>

Methods

__ctor__injectID(GDID)

Internal framework method, developers: never call

Declaration
protected void __ctor__injectID(GDID id)
Parameters
Type Name Description
GDID id

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

Declaration
public Parcel DeepClone()
Returns
Type Description
Parcel

DoMerge(IEnumerable<Parcel>)

Override to merge other parcels into this one. Return true if merge changed the payload. See Merge(). This implementation throws an exception

Declaration
protected virtual bool DoMerge(IEnumerable<Parcel> others)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<Parcel> others
Returns
Type Description
System.Boolean

DoOpen()

Override to perform actions when parcel is unsealed (opened) for modification

Declaration
protected virtual void DoOpen()

DoSeal(IBank)

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

Declaration
protected virtual void DoSeal(IBank bank)
Parameters
Type Name Description
IBank bank

DoValidate(IBank)

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)

Declaration
protected abstract void DoValidate(IBank bank)
Parameters
Type Name Description
IBank bank

Equals(Object)

Tests for parcel equality based on the same type and GDID value

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
System.Object obj
Returns
Type Description
System.Boolean
Overrides
System.Object.Equals(System.Object)

GetDistributedStableHash()

Declaration
public ulong GetDistributedStableHash()
Returns
Type Description
System.UInt64

GetHashCode()

Generates hash code based on parcel type and GDID value

Declaration
public override int GetHashCode()
Returns
Type Description
System.Int32
Overrides
System.Object.GetHashCode()

GetParcelCacheTableName(Type)

Obtains parcel cache name from either it's associated DataParcelAttribute or if not defined, from parcel type full name

Declaration
public static string GetParcelCacheTableName(Type tparcel)
Parameters
Type Name Description
System.Type tparcel
Returns
Type Description
System.String

Merge(IEnumerable<Parcel>)

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.

Declaration
public bool Merge(IEnumerable<Parcel> others)
Parameters
Type Name Description
System.Collections.Generic.IEnumerable<Parcel> others

Other parcel versions/data
Returns
Type Description
System.Boolean

True if Merge() generated newer version/changed payload. False when Merge did not/could not change existing parcel

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

Declaration
public void Open()

Seal(IBank)

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

Declaration
public void Seal(IBank bank)
Parameters
Type Name Description
IBank bank

ToString()

Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

Validate(IBank)

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

Declaration
public void Validate(IBank bank)
Parameters
Type Name Description
IBank bank

Explicit Interface Implementations

ICachePolicy.CacheTableName

Implements IParcelCachePolicy contract. The implementation returns null for parcel.

Declaration
string ICachePolicy.CacheTableName { get; }
Returns
Type Description
System.String

Implements

System.IDisposable

Extension Methods