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

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

Go to download

SnappyData store based off Pivotal GemFireXD

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;
import com.gemstone.gemfire.cache.RegionService;
/**
 * PdxInstanceFactory gives you a way to create PdxInstances.
 * Call the write methods to populate the field data and then call {@link #create()}
 * to produce an actual instance that contains the data.
 * To create a factory call {@link RegionService#createPdxInstanceFactory(String)}.
 * A factory can only create a single instance. To create multiple instances create
 * multiple factories or use {@link PdxInstance#createWriter()} to create subsequent instances.
 * Using {@link PdxInstance#createWriter()} is usually faster.
 * 
 * @author darrel
 * @since 6.6.2
 */
public interface PdxInstanceFactory {
  /**
   * Create a {@link PdxInstance}. The instance
   * will contain any data written to this factory
   * using the write methods.
   * @return the created instance
   * @throws IllegalStateException if called more than once
   */
  public PdxInstance create();

  /**
   * 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if checkPortability is true and a non-portable object is serialized
   * @throws PdxSerializationException if serialization of the field fails.
   * @since 6.6.2
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if checkPortability is true and a non-portable element is serialized
   * @throws PdxSerializationException if serialization of the field fails.
   * @since 6.6.2
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if serialization of the field fails.
   */
  public  PdxInstanceFactory 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 PdxInstanceFactory
   * @throws PdxFieldAlreadyExistsException if the named field has already been written
   * @throws PdxSerializationException if checkPortability is true and a non-portable object is serialized
   * @throws PdxSerializationException if serialization of the field fails.
   * @since 6.6.2
   */
  public  PdxInstanceFactory writeField(String fieldName, VT fieldValue, Class fieldType, boolean checkPortability);

  /**
   * 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 PdxInstanceFactory
   * @throws PdxFieldDoesNotExistException if the named field has not already been written.
   */
  public PdxInstanceFactory markIdentityField(String fieldName);
}
    
    
    
    
    
    
            
    
    
    
            
    

    
    
    
    




    
    
    © 2015 - 2024 Weber Informatics LLC | Privacy Policy