/*
* 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.
*/
package org.apache.geode.pdx;
import java.util.List;
import org.apache.geode.cache.CacheFactory;
import org.apache.geode.cache.client.ClientCacheFactory;
/**
* 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 GemFire. 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 Java objects by configuring the Cache to prefer PDX
* instances during deserialization. This can be done in <code>cache.xml</code> by setting the
* attribute <code>read-serialized</code> to true on the <code>pdx</code> element. Or it can be done
* programmatically using either the {@link CacheFactory#setPdxReadSerialized(boolean)
* setPdxReadSerialized} or {@link ClientCacheFactory#setPdxReadSerialized(boolean) client
* setPdxReadSerialized} method. Once this preference is configured, then any time deserialization
* of a PDX is done it will deserialize into a PdxInstance.
* <P>
* PdxInstances are immutable. If you want to change one call {@link #createWriter}.
* <p>
* A PdxInstance's fields will always be those of the version it represents. So if you add a field
* to your domain class you can end up with a PdxInstance for version 1 (that does not have the
* field) and a PdxInstance for version 2. The PdxInstance for version 1 will not have the added
* field and the PdxInstance for version 2 will have the field. This differs from deserialization of
* a pdx back to a domain class. In that case if version 2 is deserializing version 1 PdxReader will
* return a default value for the added field even though version 1 has no knowledge of it.
*
* @since GemFire 6.6
*/
public interface PdxInstance extends java.io.Serializable {
/**
* Return the full name of the class that this pdx instance represents.
*
* @return the name of the class that this pdx instance represents.
* @since GemFire 6.6.2
*/
public String getClassName();
/**
* Returns true if this instance represents an enum. Enum's have a String field named "name" and
* an int field named "ordinal". It is ok to cast a PdxInstance that represents an enum to
* {@link java.lang.Comparable}. PdxInstances representing enums are not writable.
*
* @return true if this instance represents an enum.
*/
public boolean isEnum();
/**
* Deserializes and returns the domain object that this instance represents.
*
* @return the deserialized domain object.
* @throws PdxSerializationException if the instance could not be deserialized
*/
public Object getObject();
/**
* Checks if the named field exists and returns the result.
* <p>
* This can be useful when writing code that handles more than one version of a PDX class.
*
* @param fieldName the name of the field to check
* @return <code>true</code> if the named field exists; otherwise <code>false</code>
*/
public boolean hasField(String fieldName);
/**
* Return an unmodifiable list of the field names on this PdxInstance.
*
* @return an unmodifiable list of the field names on this PdxInstance
*/
public List<String> getFieldNames();
/**
* Checks if the named field was {@link PdxWriter#markIdentityField(String) marked} as an identity
* field.
* <p>
* 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 <em>marked</em>.
*
* @param fieldName the name of the field to check
* @return <code>true</code> if the named field exists and was marked as an identify field;
* otherwise <code>false</code>
*/
public boolean isIdentityField(String fieldName);
/**
* Reads the named field and returns its value. If the field does not exist <code>null</code> is
* returned.
* <p>
* 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 {@link #hasField(String) hasField} method can be used
* to figure out which if these two cases is true.
* <p>
* If an Object[] is deserialized by this call then that array's component type will be
* <code>Object.class</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.
*
* @param fieldName name of the field to read
*
* @return If this instance has the named field then the field's value is returned, otherwise
* <code>null</code> is returned.
* @throws PdxSerializationException if the field could not be deserialized
*/
public Object getField(String fieldName);
/**
* Returns true if the given object is equals to this instance.
* <p>
* 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 {@link #getObject()} it will not be equal to this
* instance.
* <p>
* Otherwise equality of two PdxInstances is determined as follows:
* <ol>
* <li>The domain class name must be equal for both PdxInstances
* <li>Each identity field must be equal.
* </ol>
* 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
* {@link PdxWriter#markIdentityField(String) markIdentityField} then only the marked identity
* fields are its identity fields. Otherwise all its fields are identity fields.
* <P>
* An identity field is equal if all the following are true:
* <ol>
* <li>The field name is equal.
* <li>The field type is equal.
* <li>The field value is equal.
* </ol>
* <P>
* 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
* {@link java.util.Arrays#deepEquals(Object[], Object[]) deepEquals} is used to determine
* equality. Otherwise {@link Object#equals(Object) equals} is used.
* <P>
* If a field's type is <code>OBJECT[]</code> then its value must be deserialized and
* {@link java.util.Arrays#deepEquals(Object[], Object[]) deepEquals} is used to determine
* equality.
* <P>
* 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.
* <P>
* Note that any fields that have objects that do not override {@link Object#equals(Object)
* equals} will cause equals to return false when you might have expected it to return true. The
* only exceptions to this are those that call
* {@link java.util.Arrays#deepEquals(Object[], Object[]) deepEquals} as noted above. You should
* either override equals and hashCode in these cases or mark other fields as your identity
* fields.
*
* @param other the other instance to compare to this.
* @return <code>true</code> if this instance is equal to <code>other</code>.
*/
public boolean equals(Object other);
/**
* Generates a hashCode based on the identity fields of this PdxInstance.
* <p>
* If a PdxInstance has marked identity fields using {@link PdxWriter#markIdentityField(String)
* markIdentityField} then only the marked identity fields are its identity fields. Otherwise all
* its fields are identity fields.
* <p>
* If an identity field is of type <code>OBJECT</code> then it is deserialized. If the
* deserialized object is an array then {@link java.util.Arrays#deepHashCode(Object[])
* deepHashCode} is used. Otherwise {@link Object#hashCode() hashCode} is used.
* <p>
* If an identity field is of type <code>OBJECT[]</code> this it is deserialized and
* {@link java.util.Arrays#deepHashCode(Object[]) deepHashCode} is used.
* <p>
* Otherwise the field is not deserialized and the raw bytes of its value are used to compute the
* hash code.
* <p>
* The algorithm used to compute the hashCode is: hashCode = 1; foreach (field:
* sortedIdentityFields()) { if (field.isDefaultValue()) continue; if (field.isArray()) { hashCode
* = hashCode*31 + Arrays.deepHashCode(field); } else { hashCode = hashCode*31 + field.hashCode();
* } } if (hashCode == 0) { hashCode = 1; }
*/
public int hashCode();
/**
* Prints out all of the identity fields of this PdxInstance.
* <p>
* If a PdxInstance has marked identity fields using {@link PdxWriter#markIdentityField(String)
* markIdentityField} then only the marked identity fields are its identity fields. Otherwise all
* its fields are identity fields.
*/
public String toString();
/**
* Creates and returns a {@link WritablePdxInstance} 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.
*
* @return a {@link WritablePdxInstance}
* @throws IllegalStateException if the PdxInstance is an enum.
*/
public WritablePdxInstance createWriter();
}