com.tangosol.io.pof.PofWriter Maven / Gradle / Ivy
Show all versions of coherence Show documentation
/*
* Copyright (c) 2000, 2020, Oracle and/or its affiliates.
*
* Licensed under the Universal Permissive License v 1.0 as shown at
* http://oss.oracle.com/licenses/upl.
*/
package com.tangosol.io.pof;
import com.tangosol.util.Binary;
import com.tangosol.util.LongArray;
import java.io.IOException;
import java.math.BigDecimal;
import java.math.BigInteger;
import java.sql.Timestamp;
import java.time.LocalDate;
import java.time.LocalDateTime;
import java.time.LocalTime;
import java.time.OffsetDateTime;
import java.time.OffsetTime;
import java.time.ZonedDateTime;
import java.util.Collection;
import java.util.Date;
import java.util.Map;
/**
* The PofWriter interface provides the capability of writing a set of
* non-primitive Java types ("user types") to a POF stream as an ordered
* sequence of indexed properties.
*
* The serialized format of a POF user type is as follows:
*
* - Type Identifier
* - Version Identifier
* - [Property Index, Property Value]*
* - -1
*
* The type identifier is an integer value greater than or equal to zero that
* identifies the non-primitive Java type. The type identifier has no explicit
* or self-describing meaning within the POF stream itself; in other words,
* the type identifier does not contain the actual class definition. Instead,
* the PofWriter and corresponding {@link PofReader} share a
* {@link PofContext} which contains the necessary meta-data, including type
* identifier to Java type mappings.
*
* The version identifier is used to support both backwards and forwards
* compatibility of serialized POF user types. Versioning of user types allows
* the addition of new properties to a user type, but not the replacement or
* removal of properties that existed in a previous version of the user type.
*
* When a version v1 of a user type written by a PofWriter is read by
* a PofReader that supports version v2 of the same user type, the
* PofReader returns default values for the additional properties of the User
* Type that exist in v2 but do not exist in v1. Conversely,
* when a version v2 of a user type written by a PofWriter is read by
* a PofReader that supports version v1 of the same user type, the
* instance of user type v1 must store those additional opaque
* properties for later encoding. The PofReader enables the user type to store
* off the opaque properties in binary form (see
* {@link PofReader#readRemainder}). When the user type is re-encoded, it must
* be done so using the version identifier v2, since it is including
* the unaltered v2 properties. The opaque properties are subsequently
* included in the POF stream using the {@link #writeRemainder} method.
*
* Following the version identifier is an ordered sequence of index/value
* pairs, each of which is composed of a property index encoded as
* non-negative integer value whose value is greater than the previous
* property index, and a property value encoded as a POF value. The user type
* is finally terminated with an illegal property index of -1.
*
* Note: To read a property that was written using a PofWriter method,
* the corresponding read method on {@link PofReader} must be used.
* For example, if a property was written using {@link #writeByteArray},
* {@link PofReader#readByteArray} must be used to read the property.
*
* @author cp/jh 2006.07.13
*
* @see PofContext
* @see PofReader
*
* @since Coherence 3.2
*/
public interface PofWriter
{
// ----- primitive value support ----------------------------------------
/**
* Write a boolean property to the POF stream.
*
* @param iProp the property index
* @param f the boolean property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeBoolean(int iProp, boolean f)
throws IOException;
/**
* Write a byte property to the POF stream.
*
* @param iProp the property index
* @param b the byte property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeByte(int iProp, byte b)
throws IOException;
/**
* Write a char property to the POF stream.
*
* @param iProp the property index
* @param ch the char property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeChar(int iProp, char ch)
throws IOException;
/**
* Write a short property to the POF stream.
*
* @param iProp the property index
* @param n the short property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeShort(int iProp, short n)
throws IOException;
/**
* Write a int property to the POF stream.
*
* @param iProp the property index
* @param n the int property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeInt(int iProp, int n)
throws IOException;
/**
* Write a long property to the POF stream.
*
* @param iProp the property index
* @param n the long property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeLong(int iProp, long n)
throws IOException;
/**
* Write a float property to the POF stream.
*
* @param iProp the property index
* @param fl the float property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeFloat(int iProp, float fl)
throws IOException;
/**
* Write a double property to the POF stream.
*
* @param iProp the property index
* @param dfl the double property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDouble(int iProp, double dfl)
throws IOException;
// ----- primitive array support ----------------------------------------
/**
* Write a boolean[] property to the POF stream.
*
* @param iProp the property index
* @param af the boolean[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeBooleanArray(int iProp, boolean[] af)
throws IOException;
/**
* Write a byte[] property to the POF stream.
*
* @param iProp the property index
* @param ab the byte[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeByteArray(int iProp, byte[] ab)
throws IOException;
/**
* Write a char[] property to the POF stream.
*
* @param iProp the property index
* @param ach the char[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeCharArray(int iProp, char[] ach)
throws IOException;
/**
* Write a short[] property to the POF stream.
*
* @param iProp the property index
* @param an the short[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeShortArray(int iProp, short[] an)
throws IOException;
/**
* Write a int[] property to the POF stream.
*
* @param iProp the property index
* @param an the int[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeIntArray(int iProp, int[] an)
throws IOException;
/**
* Write a long[] property to the POF stream.
*
* @param iProp the property index
* @param an the long[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeLongArray(int iProp, long[] an)
throws IOException;
/**
* Write a float[] property to the POF stream.
*
* @param iProp the property index
* @param afl the float[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeFloatArray(int iProp, float[] afl)
throws IOException;
/**
* Write a double[] property to the POF stream.
*
* @param iProp the property index
* @param adfl the double[] property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDoubleArray(int iProp, double[] adfl)
throws IOException;
// ----- object value support -------------------------------------------
/**
* Write a BigInteger property to the POF stream.
*
* @param iProp the property index
* @param n the BigInteger property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IllegalStateException if the given BigInteger does not fit
* into 128 bits
* @throws IOException if an I/O error occurs
*/
public void writeBigInteger(int iProp, BigInteger n)
throws IOException;
/**
* Write a RawQuad property to the POF stream.
*
* @param iProp the property index
* @param qfl the RawQuad property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeRawQuad(int iProp, RawQuad qfl)
throws IOException;
/**
* Write a BigDecimal property to the POF stream.
*
* @param iProp the property index
* @param dec the BigDecimal property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IllegalStateException if the signed unscaled form of the given
* BigDecimal does not fit into 128 bits
* @throws IOException if an I/O error occurs
*/
public void writeBigDecimal(int iProp, BigDecimal dec)
throws IOException;
/**
* Write a {@link Binary} property to the POF stream.
*
* @param iProp the property index
* @param bin the Binary property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeBinary(int iProp, Binary bin)
throws IOException;
/**
* Write a String property to the POF stream.
*
* @param iProp the property index
* @param s the String property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeString(int iProp, String s)
throws IOException;
/**
* Write a Date property to the POF stream in ISO8601 format.
*
* This method encodes the year, month and day information of the
* specified Date object. No time or timezone information is
* encoded.
*
* @param iProp the property index
* @param dt the Date property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDate(int iProp, Date dt)
throws IOException;
/**
* Write a LocalDate property to the POF stream in ISO8601 format.
*
* This method encodes the year, month and day information of the
* specified LocalDate object. No time or timezone information is
* encoded.
*
* @param iProp the property index
* @param dt the LocalDate property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDate(int iProp, LocalDate dt)
throws IOException;
/**
* Write a Date property to the POF stream in ISO8601 format.
*
* This method encodes the year, month, day, hour, minute, second and
* millisecond information of the specified Date object. No
* timezone information is encoded.
*
* @param iProp the property index
* @param dt the Date property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDateTime(int iProp, Date dt)
throws IOException;
/**
* Write a LocalDateTime property to the POF stream in ISO8601 format.
*
* This method encodes the year, month, day, hour, minute, second and
* millisecond information of the specified LocalDateTime object. No
* timezone information is encoded.
*
* @param iProp the property index
* @param dt the LocalDateTime property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDateTime(int iProp, LocalDateTime dt)
throws IOException;
/**
* Write a Timestamp property to the POF stream in ISO8601
* format.
*
* This method encodes the year, month, day, hour, minute, second,
* millisecond and nanosecond information of the specified
* Timestamp object. No timezone information is encoded.
*
* @param iProp the property index
* @param dt the Timestamp property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDateTime(int iProp, Timestamp dt)
throws IOException;
/**
* Write a Date property to the POF stream in ISO8601 format.
*
* This method encodes the year, month, day, hour, minute, second,
* millisecond and timezone information of the specified Date
* object.
*
* @param iProp the property index
* @param dt the Date property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDateTimeWithZone(int iProp, Date dt)
throws IOException;
/**
* Write a OffsetDateTime property to the POF stream in ISO8601 format.
*
* This method encodes the year, month, day, hour, minute, second,
* millisecond and timezone information of the specified OffsetDateTime
* object.
*
* @param iProp the property index
* @param dt the OffsetDateTime property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDateTimeWithZone(int iProp, OffsetDateTime dt)
throws IOException;
/**
* Write a ZonedDateTime property to the POF stream in ISO8601 format.
*
* This method encodes the year, month, day, hour, minute, second,
* millisecond and timezone information of the specified ZonedDateTime
* object.
*
* @param iProp the property index
* @param dt the ZonedDateTime property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public default void writeDateTimeWithZone(int iProp, ZonedDateTime dt)
throws IOException
{
writeDateTimeWithZone(iProp, dt.toOffsetDateTime());
}
/**
* Write a Timestamp property to the POF stream in ISO8601
* format.
*
* This method encodes the year, month, day, hour, minute, second,
* millisecond, nanosecond and timezone information of the specified
* Timestamp object.
*
* @param iProp the property index
* @param dt the Timestamp property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeDateTimeWithZone(int iProp, Timestamp dt)
throws IOException;
/**
* Write a Date property to the POF stream in ISO8601 format.
*
* This method encodes the hour, minute, second and millisecond
* information of the specified Date object. No year, month, day
* or timezone information is encoded.
*
* @param iProp the property index
* @param dt the Date property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeTime(int iProp, Date dt)
throws IOException;
/**
* Write a LocalTime property to the POF stream in ISO8601 format.
*
* This method encodes the hour, minute, second and millisecond
* information of the specified LocalTime object. No year, month, day
* or timezone information is encoded.
*
* @param iProp the property index
* @param dt the LocalTime property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeTime(int iProp, LocalTime dt)
throws IOException;
/**
* Write a Timestamp property to the POF stream in ISO8601
* format.
*
* This method encodes the hour, minute, second, millisecond and
* nanosecond information of the specified Timestamp object.
*
* @param iProp the property index
* @param dt the Timestamp property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeTime(int iProp, Timestamp dt)
throws IOException;
/**
* Write a Date property to the POF stream in ISO8601 format.
*
* This method encodes the hour, minute, second, millisecond and timezone
* information of the specified Date object. No year, month or
* day information is encoded.
*
* @param iProp the property index
* @param dt the Date property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeTimeWithZone(int iProp, Date dt)
throws IOException;
/**
* Write a OffsetTime property to the POF stream in ISO8601 format.
*
* This method encodes the hour, minute, second, millisecond and timezone
* information of the specified OffsetTime object. No year, month or
* day information is encoded.
*
* @param iProp the property index
* @param dt the OffsetTime property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeTimeWithZone(int iProp, OffsetTime dt)
throws IOException;
/**
* Write a Timestamp property to the POF stream in ISO8601
* format.
*
* This method encodes the hour, minute, second, millisecond, nanosecond
* and timezone information of the specified Timestamp object. No
* year, month or day information is encoded.
*
* @param iProp the property index
* @param dt the Timestamp property value to write in ISO8601
* format
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeTimeWithZone(int iProp, Timestamp dt)
throws IOException;
/**
* Write a RawDate property to the POF stream.
*
* @param iProp the property index
* @param date the RawDate property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeRawDate(int iProp, RawDate date)
throws IOException;
/**
* Write a RawTime property to the POF stream.
*
* @param iProp the property index
* @param time the RawTime property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeRawTime(int iProp, RawTime time)
throws IOException;
/**
* Write a RawDateTime property to the POF stream.
*
* @param iProp the property index
* @param dt the RawDateTime property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeRawDateTime(int iProp, RawDateTime dt)
throws IOException;
/**
* Write a RawYearMonthInterval property to the POF stream.
*
* @param iProp the property index
* @param interval the RawYearMonthInterval property value to
* write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeRawYearMonthInterval(int iProp, RawYearMonthInterval interval)
throws IOException;
/**
* Write a RawTimeInterval property to the POF stream.
*
* @param iProp the property index
* @param interval the RawTimeInterval property value to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeRawTimeInterval(int iProp, RawTimeInterval interval)
throws IOException;
/**
* Write a RawDayTimeInterval property to the POF stream.
*
* @param iProp the property index
* @param interval the RawDayTimeInterval property value to
* write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IOException if an I/O error occurs
*/
public void writeRawDayTimeInterval(int iProp, RawDayTimeInterval interval)
throws IOException;
/**
* Write an Object property to the POF stream.
*
* The given object must be an instance of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for the object must be obtainable
* from the {@link PofContext} associated with this PofWriter.
*
* @param iProp the property index
* @param o the Object property to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; or if the given property cannot be
* encoded into a POF stream
* @throws IOException if an I/O error occurs
*/
public void writeObject(int iProp, Object o)
throws IOException;
// ----- collection support ---------------------------------------------
/**
* Write an Object[] property to the POF stream.
*
* Each element of the given array must be an instance (or an array of
* instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each element of the array must
* be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* @param type of the elements in the array
* @param iProp the property index
* @param ao the Object[] property to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; or if the given property cannot be
* encoded into a POF stream
* @throws IOException if an I/O error occurs
*/
public void writeObjectArray(int iProp, T[] ao)
throws IOException;
/**
* Write a uniform Object[] property to the POF stream.
*
* Each element of the given array must be an instance (or an array of
* instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each element of the array must
* be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* Additionally, the type of each element must be equal to the specified
* class.
*
* @param the type of the elements in the array
* @param iProp the property index
* @param ao the Object[] property to write
* @param clz the class of all elements; must not be null
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; if the given property cannot be
* encoded into a POF stream; or if the type of one or more
* elements of the array is not equal to the specified class
* @throws IOException if an I/O error occurs
*/
public void writeObjectArray(int iProp, T[] ao, Class clz)
throws IOException;
/**
* Write a Collection property to the POF stream.
*
* Each element of the given Collection must be an instance (or an array
* of instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each element of the Collection
* must be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* @param the type of elements in Collection
* @param iProp the property index
* @param coll the Collection property to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; or if the given property cannot be
* encoded into a POF stream
* @throws IOException if an I/O error occurs
*/
public void writeCollection(int iProp, Collection coll)
throws IOException;
/**
* Write a uniform Collection property to the POF stream.
*
* Each element of the given Collection must be an instance (or an array
* of instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each element of the Collection
* must be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* Additionally, the type of each element must be equal to the specified
* class.
*
* @param the type of elements in the Collection
* @param iProp the property index
* @param coll the Collection property to write
* @param clz the class of all elements; must not be null
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; if the given property cannot be
* encoded into a POF stream; or if the type of one or more
* elements of the Collection is not equal to the specified class
* @throws IOException if an I/O error occurs
*/
public void writeCollection(int iProp, Collection coll, Class clz)
throws IOException;
/**
* Write a LongArray property to the POF stream.
*
* Each element of the given LongArray must be an instance (or an array of
* instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each element of the LongArray
* must be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* @param the type of elements in LongArray
* @param iProp the property index
* @param la the LongArray property to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; or if the given property cannot be
* encoded into a POF stream
* @throws IOException if an I/O error occurs
*/
public void writeLongArray(int iProp, LongArray la)
throws IOException;
/**
* Write a uniform LongArray property to the POF stream.
*
* Each element of the given LongArray must be an instance (or an array of
* instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each element of the LongArray
* must be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* Additionally, the type of each element must be equal to the specified
* class.
*
* @param the type of elements in LongArray
* @param iProp the property index
* @param la the LongArray property to write
* @param clz the class of all elements; must not be null
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; if the given property cannot be
* encoded into a POF stream; or if the type of one or more
* elements of the LongArray is not equal to the specified class
* @throws IOException if an I/O error occurs
*/
public void writeLongArray(int iProp, LongArray la, Class clz)
throws IOException;
/**
* Write a Map property to the POF stream.
*
* Each key and value of the given Map must be an instance (or an array of
* instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each key and value of the Map
* must be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* @param the key type
* @param the value type
* @param iProp the property index
* @param map the Map property to write
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; or if the given property cannot be
* encoded into a POF stream
* @throws IOException if an I/O error occurs
*/
public void writeMap(int iProp, Map map)
throws IOException;
/**
* Write a uniform key Map property to the POF stream.
*
* Each key and value of the given Map must be an instance (or an array of
* instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each key and value of the Map
* must be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* Additionally, the type of each key must be equal to the specified
* class.
*
* @param the key type
* @param the value type
* @param iProp the property index
* @param map the Map property to write
* @param clzKey the class of all keys; must not be null
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; if the given property cannot be
* encoded into a POF stream; or if the type of one or more keys
* is not equal to the specified class
* @throws IOException if an I/O error occurs
*/
public void writeMap(int iProp, Map map, Class clzKey)
throws IOException;
/**
* Write a uniform Map property to the POF stream.
*
* Each key and value of the given Map must be an instance (or an array of
* instances) of one of the following:
*
* - boolean[]
* - byte[]
* - char[]
* - short[]
* - int[]
* - long[]
* - float[]
* - double[]
* - Boolean
* - Byte
* - Char
* - Short
* - Integer
* - Long
* - BigInteger
* - Float
* - Double
* - {@link RawQuad}
* - BigDecimal
* - {@link Binary}
* - String
* - Date
* - {@link RawDate}
* - {@link RawTime}
* - {@link RawDateTime}
* - {@link RawYearMonthInterval}
* - {@link RawTimeInterval}
* - {@link RawDayTimeInterval}
* - Collection
* - {@link LongArray}
* - {@link PortableObject}
*
*
* Otherwise, a {@link PofSerializer} for each key and value of the Map
* must be obtainable from the {@link PofContext} associated with this
* PofWriter.
*
* Additionally, the type of each key and value must be equal to the
* specified key class and value class respectively.
*
* @param the key type
* @param the value type
* @param iProp the property index
* @param map the Map property to write
* @param clzKey the class of all keys; must not be null
* @param clzValue the class of all values; must not be null
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream; if the given property cannot be
* encoded into a POF stream; or if the type of one or more keys
* or values of the Map is not equal to the specified key or value
* class
* @throws IOException if an I/O error occurs
*/
public void writeMap(int iProp, Map map, Class clzKey, Class clzValue)
throws IOException;
// ----- POF user type support ------------------------------------------
/**
* Return the PofContext object used by this PofWriter to serialize user
* types to a POF stream.
*
* @return the PofContext object that contains user type meta-data
*/
public PofContext getPofContext();
/**
* Configure the PofContext object used by this PofWriter to serialize
* user types to a POF stream.
*
* Note: this is an advanced method that should be used with care. For
* example, if this method is being used to switch to another PofContext
* mid-POF stream, it is important to eventually restore the original
* PofContext. For example:
*
* PofContext ctxOrig = writer.getPofContext();
* try
* {
* // switch to another PofContext
* PofContext ctxNew = ...;
* writer.setContext(ctxNew);
*
* // output POF data using the writer
* }
* finally
* {
* // restore the original PofContext
* writer.setPofContext(ctxOrig);
* }
*
*
* @param ctx the new PofContext; must not be null
*/
public void setPofContext(PofContext ctx);
/**
* Determine the user type that is currently being written.
*
* @return the user type identifier, or -1 if the PofWriter is not
* currently writing a user type
*/
public int getUserTypeId();
/**
* Determine the version identifier of the user type that is currently
* being written.
*
* @return the integer version ID of the user type; always non-negative
*
* @throws IllegalStateException if no user type is being written
*/
public int getVersionId();
/**
* Set the version identifier of the user type that is currently being
* written.
*
* @param nVersionId the user type identifier; must be non-negative
*
* @throws IllegalArgumentException if the given version ID is negative
* @throws IllegalStateException if no user type is being written
*/
public void setVersionId(int nVersionId);
/**
* Obtain a PofWriter that can be used to write a set of properties into
* a single property of the current user type. The returned PofWriter is
* only valid from the time that it is returned until the next call is
* made to this PofWriter.
*
* @param iProp the property index
*
* @return a PofWriter whose contents are nested into a single property
* of this PofWriter
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IllegalStateException if no user type is being written
* @throws IOException if an I/O error occurs
*
* @since Coherence 3.6
*/
public PofWriter createNestedPofWriter(int iProp)
throws IOException;
/**
* Obtain a PofWriter that can be used to write a set of properties into
* a single property of the current user type. The returned PofWriter is
* only valid from the time that it is returned until the next call is
* made to this PofWriter.
*
* @param iProp the property index
* @param nTypeId the type identifier of the nested property
*
* @return a PofWriter whose contents are nested into a single property
* of this PofWriter
*
* @throws IllegalArgumentException if the property index is invalid, or
* is less than or equal to the index of the previous property
* written to the POF stream
* @throws IllegalStateException if no user type is being written
* @throws IOException if an I/O error occurs
*
* @since Coherence 12.2.1
*/
public PofWriter createNestedPofWriter(int iProp, int nTypeId)
throws IOException;
/**
* Write the remaining properties to the POF stream, terminating the
* writing of the current user type. As part of writing out a user type,
* this method must be called by the PofSerializer that is writing out the
* user type, or the POF stream will be corrupted.
*
* Calling this method terminates the current user type by writing a -1 to
* the POF stream after the last indexed property. Subsequent calls to the
* various writeXYZ methods of this interface will fail after
* this method is called.
*
* @param binProps a Binary object containing zero or more indexed
* properties in binary POF encoded form; may be null
*
* @throws IllegalStateException if no user type is being written
* @throws IOException if an I/O error occurs
*/
public void writeRemainder(Binary binProps)
throws IOException;
}