---
title:  Program Your Application to Use IPdxInstance
---

<!--
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.
-->

An `IPdxInstance` is a lightweight wrapper around PDX serialized bytes. It provides applications with run-time access to fields of a PDX serialized object.

You can configure your cache to return an `IPdxInstance` when a PDX serialized object is deserialized instead of deserializing the object to a domain class. You can then program your application code that reads your entries to handle `IPdxInstances` fetched from the cache.

**Note:**
This option applies only to entry retrieval that you explicitly code using methods like `EntryEvent.getNewValue` and `Region.get`, as you do inside functions or in cache listener code. This does not apply to querying because the query engine retrieves the entries and handles object access for you.

**Note:**
`IPdxInstance` overrides any custom implementation you might have coded for your object's `equals` and `hashcode` methods.

**Procedure**

1.  In the `cache.xml` file of the server member where entry fetches are run, set the `<pdx>` read-serialized attribute to true.

    Data is not necessarily accessed on the member that you have coded for it. For example, if a client application runs a function on a server, the actual data access is done on the server, so you set read-serialized to true on the server.

    For example:

    ``` pre
    // Cache configuration setting PDX read behavior
                  <cache>
                    <pdx read-serialized="true" />
    ... </cache>
    ```

2.  Write the application code that fetches data from the cache to handle a `IPdxInstance`. If you are sure you will only retrieve `IPdxInstances` from the cache, you can code only for that. In many cases, a `IPdxInstance` or a domain object may be returned from your cache entry retrieval operation, so you should check the object type and handle each possible type.

    See [Use the IPdxInstanceFactory to Create IPdxInstances](using-ipdxinstancefactory.html#concept_8FA31D0D022146CE8DE2197006507AFF__example_89B7EDD2BE27423BA0CAB9B0270348B5) for an example of this.

If you configure your cache to allow PDX serialized reads, cache fetches return the data in the form it is found. If the object is not serialized, the fetch returns the domain object. If the object is serialized, the fetch returns the `PdxInstance` for the object.

**Note:**
If you are using `IPdxInstances`, you cannot use delta propagation to apply changes to PDX serialized objects.

For example, in client/server applications that are programmed and configured to handle all data activity from the client, PDX serialized reads done on the server side will always return the `IPdxInstance`. This is because all of data is serialized for transfer from the client and you are not performing any server-side activities that would deserialize the objects in the server cache.

In mixed situations, such as where a server cache is populated from client operations and also from data loads done on the server side, fetches done on the server can return a mix of `IPdxInstances` and domain objects.

When fetching data in a cache with PDX serialized reads enabled, the safest approach is to code to handle both types, receiving an Object from the fetch operation, checking the type and casting as appropriate.

## <a id="using-ipdxinstancefactory""></a> Using the IPdxInstanceFactory to Create IPdxInstances

You can use the `IPdxInstanceFactory` to create an `IPdxInstance` from raw data when the domain class is not available on the server.

This option can be useful when you need an instance of a domain class for plug-in code such as a
function or a loader. If you have the raw data for the domain object (the class name and each
field's type and data), then you can explicitly create a `IPdxInstance`. The `IPdxInstanceFactory`
is very similar to the `IPdxWriter` except that after writing each field, you need to call the
create method which returns the created `IPdxInstance.`