text: /*
   * Licensed to the Apache Software Foundation (ASF) under one or more
   * contributor license agreements.  See the NOTICE file distributed with
   * this work for additional information regarding copyright ownership.
   * The ASF licenses this file to You 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.
   */
  
  #pragma once
  
  
  namespace Apache
  {
    namespace Geode
    {
      namespace Client
      {
        using namespace System;
        using namespace System::Collections::Generic;
  
        interface class IWritablePdxInstance;
  
        /// <summary>
        ///PdxInstance provides run time access to the fields of a PDX without 
        ///deserializing the PDX. Preventing deserialization saves time
        ///and memory and does not require the domain class.
        ///This interface is implemented by NativeClient. The PdxInstance implementation 
        ///is a light weight wrapper that simply refers to the raw bytes of the PDX 
        ///that are kept in the cache.
        ///Applications can choose to access PdxInstances instead of .NET objects by 
        ///configuring the Cache to prefer PDX instances during deserialization. 
        ///This can be done in <c>cache.xml</c> by setting the attribute <c>read-serialized</c> 
        ///to true on the <c>pdx</c> element. Or it can be done programmatically using
        ///the <see cref="CacheFactory.SetPdxReadSerialized" /> 
        ///method. Once this preference is configured, then any time deserialization of a 
        ///PDX is done it will deserialize into a PdxInstance.
        ///PdxInstance are immutable. If you want to change one call
        ///<see cref="IPdxInstance.CreateWriter"/>.
        ///
        /// </summary>
        public interface class IPdxInstance : public IDisposable
        {
        public:
  
          /// <summary> 
          ///Return the full name of the class that this pdx instance represents.          
          /// </summary>
          ///<returns> the name of the class that this pdx instance represents.</returns>
          String^ GetClassName();
  
          /// <summary> 
          ///Deserializes and returns the domain object that this instance represents.           
          /// </summary>
          ///<returns> the deserialized domain object.</returns>
          Object^ GetObject();
  
          /// <summary>
          ///Checks if the named field exists and returns the result.
          ///This can be useful when writing code that handles more than one version of
          ///a PDX class.
          /// </summary>
          ///<param> fieldName the name of the field to check</param>
          ///<returns> <code>true</code> if the named field exists; otherwise <code>false</code></returns>
          bool HasField(String^ fieldName);
            
          /// <summary>
          ///Return an list of the field names on this PdxInstance.            
          /// </summary>
          ///<returns> an list of the field names on this PdxInstance</returns>
          IList<String^>^ GetFieldNames();
            
          /// <summary>
          ///Checks if the named field was <see cref="IPdxWriter.MarkIdentityField" /> marked as an identity field.
          ///Note that if no fields have been marked then all the fields are used as identity fields even though
          ///this method will return <code>false</code> since none of them have been marked.
          /// </summary>
          ///<param name="fieldName">  the name of the field to check</param>
          ///<returns> <code>true</code> if the named field exists and was marked as an identify field; otherwise <code>false</code></returns>           
          bool IsIdentityField(String^ fieldName);
  
          /// <summary>
          ///Reads the named field and returns its value. If the field does
          ///not exist <code>null</code> is returned.
          ///A <code>null</code> result indicates that the field does not exist
          ///or that it exists and its value is currently <code>null</code>.
          ///The <see cref="HasField" /> method can be used to figure out
          ///which if these two cases is true.
          ///If an Object[] is deserialized by this call then that array's component
          ///type will be <code>Object</code> instead of the original class that
          ///the array had when it was serialized. This is done so that PdxInstance objects
          ///can be added to the array.
          /// </summary>
          /// 
          ///<param name="fieldName">  name of the field to read</param>
          ///         
          ///
          ///<returns> If this instance has the named field then the field's value is returned,
          ///otherwise <code>null</code> is returned.</returns> 
          Object^ GetField(String^ fieldName);
  
          /// <summary>
          ///Returns true if the given object is equals to this instance.
          ///If <code>other</code> is not a PdxInstance then it is not equal to this instance.
          ///NOTE: Even if <code>other</code> is the result of calling <see cref="GetObject" /> it will not
          ///be equal to this instance.
          ///Otherwise equality of two PdxInstances is determined as follows:
          /// <list type="bullet">
          /// <item>
          ///<description>The domain class name must be equal for both PdxInstances</description>
          /// </item>
          /// <item>
          ///<description>Each identity field must be equal.</description>
          /// </item>
          /// </list>
          ///If one of the instances does not have a field that the other one does then equals will assume it
          ///has the field with a default value.
          ///If a PdxInstance has marked identity fields using <see cref="IPdxWriter.MarkIdentityField" /> 
          ///then only the marked identity fields are its identity fields.
          ///Otherwise all its fields are identity fields.
          ///An identity field is equal if all the following are true:
          /// <list type="bullet">
          /// <item>
          ///<description>The field name is equal.</description>
          /// </item>
          /// <item>
          ///<description>The field type is equal.</description>
          /// </item>
          /// <item>
          ///<description>The field value is equal.</description>
          /// </item>
          /// </list>
          ///If a field's type is <code>OBJECT</code> then its value must be deserialized to determine if it is equals. If the deserialized object is an array then all the array element is used to determine equality. Otherwise <see cref="Object.Equals" /> is used.
          ///If a field's type is <code>OBJECT[]</code> then its value must be deserialized and all the array element is used to determine equality.
          ///For all other field types then the value does not need to be deserialized. Instead the serialized raw bytes are compared and used to determine equality.
          ///Note that any fields that have objects that do not override <see cref="Object.Equals" /> will cause equals to return false when you might have expected it to return true.
          /// </summary>
          ///<param name="other"> the other instance to compare to this.</param>
          ///<returns> <code>true</code> if this instance is equal to <code>other</code>.</returns>
          bool Equals(Object^ other);
  
          /// <summary>
          ///Generates a hashCode based on the identity fields of
          ///this PdxInstance. 
          ///If a PdxInstance has marked identity fields using <see cref="IPdxWriter.MarkIdentityField" />
          ///then only the marked identity fields are its identity fields.
          ///Otherwise all its fields are identity fields.
          ///
          ///If an identity field is of type <code>OBJECT</code> then it is deserialized. If the deserialized object is an array then all the array element is used. Otherwise <see cref="Object.GetHashCode" /> is used.
          ///If an identity field is of type <code>OBJECT[]</code> this it is deserialized and all the array element is used.
          ///Otherwise the field is not deserialized and the raw bytes of its value are used to compute the hash code.
          /// </summary>
          int GetHashCode();
  
          /// <summary>
          ///Prints out all of the identity fields of this PdxInstance.
          ///If a PdxInstance has marked identity fields using <see cref="IPdxWriter.MarkIdentityField" />
          ///then only the marked identity fields are its identity fields.
          ///Otherwise all its fields are identity fields.
          /// </summary>
          String^ ToString();
            
          /// <summary>
          ///Creates and returns a <see cref="IWritablePdxInstance"/> whose initial
          ///values are those of this PdxInstance.
          ///This call returns a copy of the current field values so modifications
          ///made to the returned value will not modify this PdxInstance.
          /// </summary>
          ///
          ///<returns> a <see cref="IWritablePdxInstance"/></returns>  
          IWritablePdxInstance^ CreateWriter();
  
        };
      }  // namespace Client
    }  // namespace Geode
  }  // namespace Apache
  
  