Class PofStreamReader

IPofReader implementation that reads POF-encoded data from a DataReader.

Inheritance
object
PofStreamReader
PofStreamReader.UserTypeReader
Implements
Inherited Members
Namespace: Tangosol.IO.Pof
Assembly: Coherence.dll
Syntax
public class PofStreamReader : IPofReader

Constructors

PofStreamReader()

Construct a POF parser.

Declaration
protected PofStreamReader()

PofStreamReader(DataReader, IPofContext)

Construct a POF parser that will pull values from the specified stream.

Declaration
public PofStreamReader(DataReader reader, IPofContext ctx)
Parameters
Type Name Description
DataReader reader

A DataReader object.
IPofContext ctx

The IPofContext.

Fields

m_ctx

The IPofContext to use to realize user data types as .NET objects.

Declaration
protected IPofContext m_ctx
Field Value
Type Description
IPofContext

m_reader

The DataReader containing the POF stream.

Declaration
protected DataReader m_reader
Field Value
Type Description
DataReader

m_referenceMap

Lazily-constructed mapping of identities to references.

Declaration
protected ILongArray m_referenceMap
Field Value
Type Description
ILongArray

Properties

ParentParser

If this parser is contextually within a user type, obtain the parser which created this parser in order to parse the user type.

Declaration
protected virtual PofStreamReader ParentParser { get; }
Property Value
Type Description
PofStreamReader

The parser for the context within which this parser is operating.

PofContext

Gets or sets the IPofContext object used by this PofStreamReader to deserialize user types from a POF stream.

Declaration
public virtual IPofContext PofContext { get; set; }
Property Value
Type Description
IPofContext

The IPofContext object that contains user type meta-data.
Remarks

This is an advanced propertie that should be used with care. For example, if this method is being used to switch to another IPofContext mid-POF stream, it is important to eventually restore the original IPofContext. For example:

IPofContext ctxOrig = reader.PofContext;
try
{
    // switch to another IPofContext
    reader.PofContext = ...;

    // read POF data using the reader
}
finally
{
    // restore the original PofContext
    reader.PofContext = ctxOrig;
}

UserTypeId

Gets the user type that is currently being parsed.

Declaration
public virtual int UserTypeId { get; }
Property Value
Type Description
int

The user type information, or -1 if the PofStreamReader is not currently parsing a user type.

VersionId

Gets the version identifier of the user type that is currently being parsed.

Declaration
public virtual int VersionId { get; }
Property Value
Type Description
int

The integer version ID read from the POF stream; always non-negative.
Exceptions
Type Condition
InvalidOperationException

If no user type is being parsed.

Methods

AdvanceTo(int)

Advance through the POF stream until the specified property is found.

Declaration
protected virtual bool AdvanceTo(int index)
Parameters
Type Name Description
int index

The index of the property to advance to.
Returns
Type Description
bool

true if the property is found.
Remarks

If the property is found, return true, otherwise return false and advance to the first property that follows the specified property.

Exceptions
Type Condition
InvalidOperationException

if the POF stream has already advanced past the desired property.

Complete(int)

Register the completion of the parsing of a value.

Declaration
protected virtual void Complete(int index)
Parameters
Type Name Description
int index

The property index.
Exceptions
Type Condition
IOException

If an I/O error occurs.

CreateNestedPofReader(int)

Obtain a PofReader that can be used to read a set of properties from a single property of the current user type. The returned PofReader is only valid from the time that it is returned until the next call is made to this PofReader.

Declaration
public virtual IPofReader CreateNestedPofReader(int iProp)
Parameters
Type Name Description
int iProp

the property index to read from
Returns
Type Description
IPofReader

a PofReader that reads its contents from a single property of this PofReader
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property, or if no user type is being parsed.
IOException

if an I/O error occurs

EnsureReferenceRegistry()

Obtain the registry for identity-reference pairs, creating it if necessary.

Declaration
protected virtual ILongArray EnsureReferenceRegistry()
Returns
Type Description
ILongArray

The identity-reference registry, never null.

LookupIdentity(int)

Look up the specified identity and return the object to which it refers.

Declaration
protected virtual object LookupIdentity(int id)
Parameters
Type Name Description
int id

The identity.
Returns
Type Description
object

The object registered under that identity.
Exceptions
Type Condition
IOException

If the requested identity is not registered.

ReadArray(int)

Read an array of object values.

Declaration
public virtual Array ReadArray(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
Array

An array of object values, or null if there is no array data in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadArray(int, Array)

Read an array of object values.

Declaration
public virtual Array ReadArray(int index, Array array)
Parameters
Type Name Description
int index

The property index to read.
Array array

The optional array to use to store the values, or to use as a typed template for creating an array to store the values, following the documentation for ArrayList.ToArray.
Returns
Type Description
Array

An array of object values, or null if no array is passed and there is no array data in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadAsArray(int, Array)

Read a POF value as a typed object array.

Declaration
protected virtual Array ReadAsArray(int typeId, Array array)
Parameters
Type Name Description
int typeId

The type identifier of the value.
Array array

The optional array to use to store the values, or to use as a typed template for creating an array to store the values.
Returns
Type Description
Array

A typed object array.
Exceptions
Type Condition
IOException

If an I/O error occurs.

ReadAsObject(int)

Read a POF value as an Object.

Declaration
protected virtual object ReadAsObject(int typeId)
Parameters
Type Name Description
int typeId

The type identifier of the value.
Returns
Type Description
object

An Object value.
Exceptions
Type Condition
IOException

If an I/O error occurs.

ReadAsUniformObject(int)

Read a POF value in a uniform array/map as an Object.

Declaration
protected object ReadAsUniformObject(int typeId)
Parameters
Type Name Description
int typeId

The type identifier of the value.
Returns
Type Description
object

An Object value.

ReadBinary(int)

Read a Binary from the POF stream.

Declaration
public virtual Binary ReadBinary(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
Binary

The Binary property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadBinary(DataReader)

Read a Binary object from the specified DataReader in an optimal way.

Declaration
protected static Binary ReadBinary(DataReader reader)
Parameters
Type Name Description
DataReader reader

A DataReader to read from.
Returns
Type Description
Binary

The Binary data.

ReadBoolean(int)

Read a Boolean property from the POF stream.

Declaration
public virtual bool ReadBoolean(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
bool

The Boolean property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadBooleanArray(int)

Read a Boolean[] property from the POF stream.

Declaration
public virtual bool[] ReadBooleanArray(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
bool[]

The Boolean[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadByte(int)

Read a Byte property from the POF stream.

Declaration
public virtual byte ReadByte(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
byte

The Byte property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadByteArray(int)

Read a Byte[] property from the POF stream.

Declaration
public virtual byte[] ReadByteArray(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
byte[]

The Byte[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadChar(int)

Read a Char property from the POF stream.

Declaration
public virtual char ReadChar(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
char

The Char property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadCharArray(int)

Read a Char[] property from the POF stream.

Declaration
public virtual char[] ReadCharArray(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
char[]

The Char[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadCollection(int, ICollection)

Read an ICollection of object values from the POF stream.

Declaration
public virtual ICollection ReadCollection(int index, ICollection coll)
Parameters
Type Name Description
int index

The property index to read.
ICollection coll

The optional ICollection to use to store the values.
Returns
Type Description
ICollection

A collection of object values, or null if no collection is passed and there is no collection data in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadCollection<T>(int, ICollection<T>)

Read a generic ICollection<T> of object values from the POF stream.

Declaration
public virtual ICollection<T> ReadCollection<T>(int index, ICollection<T> coll)
Parameters
Type Name Description
int index

The property index to read.
ICollection<T> coll

The optional ICollection<T> to use to store the values.
Returns
Type Description
ICollection<T>

A generic collection of object values, or null if no collection is passed and there is no collection data in the POF stream.
Type Parameters
Name Description
T

The type of the elements in the collection.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadDate(int)

Read a DateTime property from the POF stream.

Declaration
public virtual DateTime ReadDate(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
DateTime

The DateTime property value.
Remarks

This method will read only the date component of a date-time value from the POF stream. It will ignore the time component if present and initialize the time-related fields of the return value to their default values.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadDateTime(int)

Read a DateTime property from the POF stream.

Declaration
public virtual DateTime ReadDateTime(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
DateTime

The DateTime property value.
Remarks

This method will attempt to read both the date and time component from the POF stream. If the value in the stream does not contain both components, the corresponding values in the returned DateTime instance will be set to default values.

If the encoded value in the POF stream contains time zone information, this method will ignore time zone information and return a literal DateTime value, as read from the stream.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadDayTimeInterval(int)

Reads a TimeSpan from the POF stream.

Declaration
public virtual TimeSpan ReadDayTimeInterval(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
TimeSpan

The TimeSpan property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadDecimal(int)

Read a Decimal from the POF stream.

Declaration
public virtual decimal ReadDecimal(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
decimal

The Decimal property value, or null if no value was available in the POF stream
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadDictionary(int, IDictionary)

Read an IDictionary of key/value pairs from the POF stream.

Declaration
public virtual IDictionary ReadDictionary(int index, IDictionary dict)
Parameters
Type Name Description
int index

The property index to read.
IDictionary dict

The optional IDictionary to initialize.
Returns
Type Description
IDictionary

An IDictionary of key/value pairs object values, or null if no dictionary is passed and there is no key/value data in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
ArgumentNullException

If dict is null.
IOException

If an I/O error occurs.

ReadDictionary<TKey, TValue>(int, IDictionary<TKey, TValue>)

Read a generic IDictionary<TKey, TValue> of key/value pairs from the POF stream.

Declaration
public virtual IDictionary<TKey, TValue> ReadDictionary<TKey, TValue>(int index, IDictionary<TKey, TValue> dictionary)
Parameters
Type Name Description
int index

The property index to read.
IDictionary<TKey, TValue> dictionary

The optional IDictionary<TKey, TValue> to initialize.
Returns
Type Description
IDictionary<TKey, TValue>

An IDictionary<TKey, TValue> of key/value pairs object values, or null if no dictionary is passed and there is no key/value data in the POF stream.
Type Parameters
Name Description
TKey

The type of the keys in the dictionary.
TValue

The type of the values in the dictionary.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
ArgumentNullException

If dictionary is null.
IOException

If an I/O error occurs.

ReadDouble(int)

Read a Double property from the POF stream.

Declaration
public virtual double ReadDouble(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
double

The Double property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadDoubleArray(int)

Read a Double[] property from the POF stream.

Declaration
public virtual double[] ReadDoubleArray(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
double[]

The Double[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadInt16(int)

Read an Int16 property from the POF stream.

Declaration
public virtual short ReadInt16(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
short

The Int16 property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadInt16Array(int)

Read an Int16[] property from the POF stream.

Declaration
public virtual short[] ReadInt16Array(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
short[]

The Int16[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadInt32(int)

Read an Int32 property from the POF stream.

Declaration
public virtual int ReadInt32(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
int

The Int32 property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadInt32Array(int)

Read an Int32[] property from the POF stream.

Declaration
public virtual int[] ReadInt32Array(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
int[]

The Int32[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadInt64(int)

Read an Int64 property from the POF stream.

Declaration
public virtual long ReadInt64(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
long

The Int64 property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadInt64Array(int)

Read an Int64[] property from the POF stream.

Declaration
public virtual long[] ReadInt64Array(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
long[]

The Int64[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadLocalDateTime(int)

Read a DateTime property from the POF stream.

Declaration
public DateTime ReadLocalDateTime(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
DateTime

The DateTime property value.
Remarks

This method will attempt to read both the date and time component from the POF stream. If the value in the stream does not contain both components, the corresponding values in the returned DateTime instance will be set to default values.

If the encoded value in the POF stream contains time zone information, this method will use it to determine and return the local time for the reading thread.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadLongArray(int, ILongArray)

Read an ILongArray of object values.

Declaration
public ILongArray ReadLongArray(int index, ILongArray array)
Parameters
Type Name Description
int index

The property index to read.
ILongArray array

The optional ILongArray object to use to store the values.
Returns
Type Description
ILongArray

An ILongArray of object values, or null if no ILongArray is passed and there is no array data in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadObject(int)

Read a property of any type, including a user type, from the POF stream.

Declaration
public virtual object ReadObject(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
object

The object value; may be null.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadRawDateTime(int)

Read a RawDateTime from the POF stream.

Declaration
public virtual RawDateTime ReadRawDateTime(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
RawDateTime

The RawDateTime property value, or null if no value was available in the POF stream.
Remarks

The RawDateTime class contains the raw date and time information that was carried in the POF stream, including raw timezone information.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadRawInt128(int)

Read an RawInt128 property from the POF stream.

Declaration
public virtual RawInt128 ReadRawInt128(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
RawInt128

The RawInt128 property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadRawTime(int)

Read a RawTime property from the POF stream.

Declaration
public virtual RawTime ReadRawTime(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
RawTime

The RawTime property value, or null if no value was available in the POF stream.
Remarks

The RawTime class contains the raw time information that was carried in the POF stream, including raw timezone information.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadRawYearMonthInterval(int)

Read a year-month interval from the POF stream.

Declaration
public virtual RawYearMonthInterval ReadRawYearMonthInterval(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
RawYearMonthInterval

The YearMonthInterval property value, or null if no value was available in the POF stream.
Remarks

The RawYearMonthInterval struct contains the raw year-month interval information that was carried in the POF stream.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadRemainder()

Read all remaining indexed properties of the current user type from the POF stream.

Declaration
public virtual Binary ReadRemainder()
Returns
Type Description
Binary

A Byte[] containing zero or more indexed properties in binary POF encoded form.
Remarks

As part of reading in a user type, this method must be called by the IPofSerializer that is reading the user type, or the read position within the POF stream will be corrupted. Subsequent calls to the various ReadXYZ methods of this interface will fail after this method is called.

Exceptions
Type Condition
InvalidOperationException

If no user type is being parsed.
IOException

If an I/O error occurs.

ReadSingle(int)

Read a Single property from the POF stream.

Declaration
public virtual float ReadSingle(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
float

The Single property value, or zero if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadSingleArray(int)

Read a Single[] property from the POF stream.

Declaration
public virtual float[] ReadSingleArray(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
float[]

The Single[] property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadString(int)

Read a String property from the POF stream.

Declaration
public virtual string ReadString(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
string

The String property value, or null if no value was available in the POF stream.
Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadTimeInterval(int)

Reads a TimeSpan from the POF stream.

Declaration
public virtual TimeSpan ReadTimeInterval(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
TimeSpan

The TimeSpan property value, or null if no value was available in the POF stream.
Remarks

This method will read only the time component of a day-time-interval value from the POF stream. It will ignore the day component if present and initialize day-related fields of the return value to their default values.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

ReadUniversalDateTime(int)

Read a DateTime property from the POF stream.

Declaration
public DateTime ReadUniversalDateTime(int index)
Parameters
Type Name Description
int index

The property index to read.
Returns
Type Description
DateTime

The DateTime property value.
Remarks

This method will attempt to read both the date and time components from the POF stream. If the value in the stream does not contain both components, the corresponding values in the returned DateTime instance will be set to default values.

If the encoded value in the POF stream contains time zone information, this method will use it to determine and return a Coordinated Universal Time (UTC) value.

Exceptions
Type Condition
InvalidOperationException

If the POF stream has already advanced past the desired property.
IOException

If an I/O error occurs.

RegisterIdentity(int, object)

Register the passed value with the passed identity.

Declaration
protected virtual void RegisterIdentity(int id, object value)
Parameters
Type Name Description
int id

The identity.
object value

The object registerd under the passed identity.
Exceptions
Type Condition
ArgumentException

If the specified identity is already registered with a different object.

RegisterIdentity(object)

Register an identity for a newly created user type instance.

Declaration
public virtual void RegisterIdentity(object o)
Parameters
Type Name Description
object o

The object to register the identity for.
Remarks

If identity/reference types are enabled, an identity is used to uniquely identify a user type instance within a POF stream. The identity immediately proceeds the instance value in the POF stream and can be used later in the stream to reference the instance.

IPofSerializer implementations must call this method with each user type instance instantiated during deserialization prior to reading any properties of the instance which are user type instances themselves.
Exceptions
Type Condition
InvalidOperationException

If no user type is being parsed.

Implements