All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.gemstone.gemfire.pdx.PdxWriter Maven / Gradle / Ivy

There is a newer version: 2.0-BETA
Show newest version
/*
 * Copyright (c) 2010-2015 Pivotal Software, Inc. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License"); you
 * may not use this file except in compliance with the License. You
 * may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * permissions and limitations under the License. See accompanying
 * LICENSE file.
 */
package com.gemstone.gemfire.pdx;

import java.util.Date;

import com.gemstone.gemfire.cache.CacheFactory;

/**
 * A PdxWriter will be passed to {@link PdxSerializable#toData(PdxWriter) toData} or 
 * {@link PdxSerializer#toData(Object, PdxWriter) PdxSerializer toData} by GemFire when it is serializing the 
 * domain class. The domain class needs to serialize instance 
 * fields using this interface. This interface is implemented 
 * by GemFire.
 * 

The order in which the fields are written must match the order in which they are * read by {@link PdxReader}. *

Field names are case sensitive. *

All methods on this interface return itself to allow method calls to be * chained together. * * @author darrel * @since 6.6 */ public interface PdxWriter { /** * Writes the named field with the given value to the serialized form. * The fields type is char. *

Java char is mapped to .NET System.Char. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeChar(String fieldName, char value); /** * Writes the named field with the given value to the serialized form. * The fields type is boolean. *

Java boolean is mapped to .NET System.Boolean. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeBoolean(String fieldName, boolean value); /** * Writes the named field with the given value to the serialized form. * The fields type is byte. *

Java byte is mapped to .NET System.SByte. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeByte(String fieldName, byte value); /** * Writes the named field with the given value to the serialized form. * The fields type is short. *

Java short is mapped to .NET System.Int16. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeShort(String fieldName, short value); /** * Writes the named field with the given value to the serialized form. * The fields type is int. *

Java int is mapped to .NET System.Int32. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeInt(String fieldName, int value); /** * Writes the named field with the given value to the serialized form. * The fields type is long. *

Java long is mapped to .NET System.Int64. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeLong(String fieldName, long value); /** * Writes the named field with the given value to the serialized form. * The fields type is float. *

Java float is mapped to .NET System.Float. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeFloat(String fieldName, float value); /** * Writes the named field with the given value to the serialized form. * The fields type is double. *

Java double is mapped to .NET System.Double. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeDouble(String fieldName, double value); /** * Writes the named field with the given value to the serialized form. * The fields type is Date. *

Java Date is mapped to .NET System.DateTime. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeDate(String fieldName, Date value); /** * Writes the named field with the given value to the serialized form. * The fields type is String. *

Java String is mapped to .NET System.String. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeString(String fieldName, String value); /** * Writes the named field with the given value to the serialized form. * The fields type is Object. *

* It is best to use one of the other writeXXX methods if your field type * will always be XXX. This method allows the field value to be anything * that is an instance of Object. This gives you more flexibility but more * space is used to store the serialized field. *

* Note that some Java objects serialized with this method may not be compatible with non-java languages. * To ensure that only portable objects are serialized use {@link #writeObject(String, Object, boolean)}. * * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeObject(String fieldName, Object value); /** * Writes the named field with the given value to the serialized form. * The fields type is Object. *

* It is best to use one of the other writeXXX methods if your field type * will always be XXX. This method allows the field value to be anything * that is an instance of Object. This gives you more flexibility but more * space is used to store the serialized field. *

* Note that some Java objects serialized with this method may not be compatible with non-java languages. * To ensure that only portable objects are serialized set the checkPortability parameter to true. * The following is a list of the Java classes that are portable and the .NET class they are mapped to: *

    *
  • instances of {@link PdxSerializable}: .NET class of same name *
  • instances of {@link PdxInstance}: .NET class of same name *
  • instances serialized by a {@link PdxSerializer}: .NET class of same name *
  • java.lang.Byte: System.SByte *
  • java.lang.Boolean: System.Boolean *
  • java.lang.Character: System.Char *
  • java.lang.Short: System.Int16 *
  • java.lang.Integer: System.Int32 *
  • java.lang.Long: System.Int64 *
  • java.lang.Float: System.Float *
  • java.lang.Double: System.Double *
  • java.lang.String: System.String *
  • java.util.Date: System.DateTime *
  • byte[]: System.Byte[] *
  • boolean[]: System.Boolean[] *
  • char[]: System.Char[] *
  • short[]: System.Int16[] *
  • int[]: System.Int32[] *
  • long[]: System.Int64[] *
  • float[]: System.Float[] *
  • double[]: System.Double[] *
  • String[]: System.String[] *
  • byte[][]: System.Byte[][] *
  • Object[]: System.Collections.Generic.List *
  • java.util.HashMap: System.Collections.Generics.IDictionary *
  • java.util.Hashtable: System.Collections.Hashtable *
  • java.util.ArrayList: System.Collections.Generic.IList *
  • java.util.Vector: System.Collections.ArrayList *
  • java.util.HashSet: CacheableHashSet *
  • java.util.LinkedHashSet: CacheableLinkedHashSet * * * @param fieldName the name of the field to write * @param value the value of the field to write * @param checkPortability if true then an exception is thrown if a non-portable object is serialized * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws NonPortableClassException if checkPortability is true and a non-portable object is serialized * @throws PdxSerializationException if serialization of the field fails. * @since 6.6.2 */ public PdxWriter writeObject(String fieldName, Object value, boolean checkPortability); /** * Writes the named field with the given value to the serialized form. * The fields type is boolean[]. *

    Java boolean[] is mapped to .NET System.Boolean[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeBooleanArray(String fieldName, boolean[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is char[]. *

    Java char[] is mapped to .NET System.Char[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeCharArray(String fieldName, char[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is byte[]. *

    Java byte[] is mapped to .NET System.Byte[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeByteArray(String fieldName, byte[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is short[]. *

    Java short[] is mapped to .NET System.Int16[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeShortArray(String fieldName, short[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is int[]. *

    Java int[] is mapped to .NET System.Int32[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeIntArray(String fieldName, int[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is long[]. *

    Java long[] is mapped to .NET System.Int64[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeLongArray(String fieldName, long[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is float[]. *

    Java float[] is mapped to .NET System.Float[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeFloatArray(String fieldName, float[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is double[]. *

    Java double[] is mapped to .NET System.Double[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeDoubleArray(String fieldName, double[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is String[]. *

    Java String[] is mapped to .NET System.String[]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeStringArray(String fieldName, String[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is Object[]. *

    Java Object[] is mapped to .NET System.Collections.Generic.List. * For how each element of the array is a mapped to .NET see {@link #writeObject(String, Object, boolean) writeObject}. * Note that this call may serialize elements that are not compatible with non-java languages. * To ensure that only portable objects are serialized use {@link #writeObjectArray(String, Object[], boolean)}. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeObjectArray(String fieldName, Object[] value); /** * Writes the named field with the given value to the serialized form. * The fields type is Object[]. *

    Java Object[] is mapped to .NET System.Collections.Generic.List. * For how each element of the array is a mapped to .NET see {@link #writeObject(String, Object, boolean) writeObject}. * Note that this call may serialize elements that are not compatible with non-java languages. * To ensure that only portable objects are serialized use {@link #writeObjectArray(String, Object[], boolean)}. * @param fieldName the name of the field to write * @param value the value of the field to write * @param checkPortability if true then an exception is thrown if a non-portable object is serialized * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws NonPortableClassException if checkPortability is true and a non-portable element is serialized * @throws PdxSerializationException if serialization of the field fails. * @since 6.6.2 */ public PdxWriter writeObjectArray(String fieldName, Object[] value, boolean checkPortability); /** * Writes the named field with the given value to the serialized form. * The fields type is byte[][]. *

    Java byte[][] is mapped to .NET System.Byte[][]. * @param fieldName the name of the field to write * @param value the value of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeArrayOfByteArrays(String fieldName, byte[][] value); /** * Writes the named field with the given value and type to the serialized form. * This method uses the fieldType to determine which writeXXX method it should call. * If it can not find a specific match to a writeXXX method it will call {@link #writeObject(String, Object) writeObject}. * This method may serialize objects that are not portable to non-java languages. * To ensure that only objects that are portable to non-java languages are serialized use {@link #writeField(String, Object, Class, boolean)} instead. *

    The fieldTypes that map to a specific method are: *

      *
    • boolean.class: {@link #writeBoolean} *
    • byte.class: {@link #writeByte} *
    • char.class: {@link #writeChar} *
    • short.class: {@link #writeShort} *
    • int.class: {@link #writeInt} *
    • long.class: {@link #writeLong} *
    • float.class: {@link #writeFloat} *
    • double.class: {@link #writeDouble} *
    • String.class: {@link #writeString} *
    • Date.class: {@link #writeDate} *
    • boolean[].class: {@link #writeBooleanArray} *
    • byte[].class: {@link #writeByteArray} *
    • char[].class: {@link #writeCharArray} *
    • short[].class: {@link #writeShortArray} *
    • int[].class: {@link #writeIntArray} *
    • long[].class: {@link #writeLongArray} *
    • float[].class: {@link #writeFloatArray} *
    • double[].class: {@link #writeDoubleArray} *
    • String[].class: {@link #writeStringArray} *
    • byte[][].class: {@link #writeArrayOfByteArrays} *
    • any other array class: {@link #writeObjectArray} *
    * Note that the object form of primitives, for example Integer.class and Long.class, map to {@link #writeObject(String, Object) writeObject}. * @param fieldName the name of the field to write * @param fieldValue the value of the field to write; this parameter's class must extend the fieldType * @param fieldType the type of the field to write * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws PdxSerializationException if serialization of the field fails. */ public PdxWriter writeField(String fieldName, VT fieldValue, Class fieldType); /** * Writes the named field with the given value and type to the serialized form. * This method uses the fieldType to determine which writeXXX method it should call. * If it can not find a specific match to a writeXXX method it will call {@link #writeObject(String, Object, boolean) writeObject}. * To ensure that only objects that are portable to non-java languages are serialized set the checkPortability parameter to true. *

    The fieldTypes that map to a specific method are: *

      *
    • boolean.class: {@link #writeBoolean} *
    • byte.class: {@link #writeByte} *
    • char.class: {@link #writeChar} *
    • short.class: {@link #writeShort} *
    • int.class: {@link #writeInt} *
    • long.class: {@link #writeLong} *
    • float.class: {@link #writeFloat} *
    • double.class: {@link #writeDouble} *
    • String.class: {@link #writeString} *
    • Date.class: {@link #writeDate} *
    • boolean[].class: {@link #writeBooleanArray} *
    • byte[].class: {@link #writeByteArray} *
    • char[].class: {@link #writeCharArray} *
    • short[].class: {@link #writeShortArray} *
    • int[].class: {@link #writeIntArray} *
    • long[].class: {@link #writeLongArray} *
    • float[].class: {@link #writeFloatArray} *
    • double[].class: {@link #writeDoubleArray} *
    • String[].class: {@link #writeStringArray} *
    • byte[][].class: {@link #writeArrayOfByteArrays} *
    • any other array class: {@link #writeObjectArray(String, Object[], boolean)} *
    * Note that the object form of primitives, for example Integer.class and Long.class, map to {@link #writeObject(String, Object, boolean) writeObject}. * @param fieldName the name of the field to write * @param fieldValue the value of the field to write; this parameter's class must extend the fieldType * @param fieldType the type of the field to write * @param checkPortability if true then an exception is thrown if a non-portable object is serialized * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if the named field has already been written * @throws NonPortableClassException if checkPortability is true and a non-portable object is serialized * @throws PdxSerializationException if serialization of the field fails. * @since 6.6.2 */ public PdxWriter writeField(String fieldName, VT fieldValue, Class fieldType, boolean checkPortability); /** * Writes the given unread fields to the serialized form. * The unread fields are obtained by calling {@link PdxReader#readUnreadFields() readUnreadFields}. *

    This method must be called first before any of the writeXXX methods is called. * @param unread the object that was returned from {@link PdxReader#readUnreadFields() readUnreadFields}. * @return this PdxWriter * @throws PdxFieldAlreadyExistsException if one of the writeXXX methods has already been called. */ public PdxWriter writeUnreadFields(PdxUnreadFields unread); /** * Indicate that the named field should be included in hashCode and equals checks * of this object on a server that is accessing {@link PdxInstance} * or when a client executes a query on a server. * * The fields that are marked as identity fields are used to generate the hashCode and * equals methods of {@link PdxInstance}. Because of this, the identity fields should themselves * either be primitives, or implement hashCode and equals. * * If no fields are set as identity fields, then all fields will be used in hashCode and equals * checks. * * The identity fields should make marked after they are written using a write* method. * * @param fieldName the name of the field to mark as an identity field. * @return this PdxWriter * @throws PdxFieldDoesNotExistException if the named field has not already been written. */ public PdxWriter markIdentityField(String fieldName); }