| --- |
| title: Programming Your Application to Use PdxInstances |
| --- |
| |
| <!-- |
| 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. |
| --> |
| |
| A `PdxInstance` is a lightweight wrapper around the raw bytes of the PDX serialized objects kept in the cache. It provides applications with run-time access to files of a PDX serialized object. <%=vars.product_name%> provides the implementation of the `PdxInstance` class. |
| |
| You can configure your cache to return a `PdxInstance` when a PDX serialized object is deserialized instead of deserializing the object to a domain class. Preventing deserialization saves both time and memory and does not require you deserialize the object to the domain class. |
| |
| This configuration can be done in cache.xml by setting the attribute `read-serialized` to `true` on the <pdx> element, or it can be done programmatically using the `CacheFactory::setPdxReadSerialized(bool)` method. |
| |
| After this preference is configured, any time a PDX object is deserialized, it is deserialized into a `PdxInstance`. |
| |
| The following is a code sample of using the `setField` API of `PdxInstance` to modify fields: |
| |
| ``` pre |
| RegionPtr rptr = getHelper()->getRegion( regionNames[0] ); |
| CacheableKeyPtr keyport = CacheableKey::create("pdxput"); |
| CacheableKeyPtr keyport1 = CacheableKey::create("pdxput2"); |
| |
| PdxInstancePtr pIPtr = dynCast<PdxInstancePtr>(rptr->get(keyport)); |
| LOG( "modifyPdxInstance get complete." ); |
| |
| WritablePdxInstancePtr wpiPtr( pIPtr->createWriter()); |
| |
| ASSERT(pIPtr != NULLPTR, "pIPtr != NULLPTR expected"); |
| int val = 0; |
| int newVal = 0; |
| ASSERT(pIPtr->hasField("m_int32") == true, "m_id1 = true expected"); |
| pIPtr->getField("m_int32", val); |
| wpiPtr->setField("m_int32", val + 1); |
| rptr->put(keyport, wpiPtr); |
| PdxInstancePtr newPiPtr = dynCast<PdxInstancePtr>(rptr->get(keyport)); |
| ASSERT(newPiPtr->hasField("m_int32") == true, "m_int32 = true expected"); |
| newPiPtr->getField("m_int32", newVal); |
| ASSERT(val + 1 == newVal, "val + 1 == newVal expected"); |
| ASSERT((*pIPtr.ptr() == *newPiPtr.ptr()) == false, |
| "PdxInstance should not be equal"); |
| ``` |
| |
| In addition to field access, `PdxInstance` also supports field modification using the `setField(fieldName)` method. The `setField` method has copy-on-write semantics. So for the modifications to be stored in the cache, the `PdxInstance` must be put into a region after `setField` has been called one or more times. |
| |
| |
