In order to be compatible with the Managed template, the data object class must have:

The Managed adapter will implement the initial set of requirements, delegating where applicable to the previously described functions. Our Account class already meets the first two requirements. So all that is needed to make it Managed-compatible is to define three functions as follows:

bool operator==(const Account& accountA, const Account& accountB)
{
return accountA.getId() == accountB.getId() &&
accountA.getDescription() == accountB.getDescription() &&
accountA.getBalance() == accountB.getBalance() &&
accountA.getLastTransactionId() ==
accountB.getLastTransactionId() &&
accountA.getCustomerId() == accountB.getCustomerId();
}
std::ostream& operator<<(std::ostream& out, const Account& account)
{
out << "Account("
<< "Id=" << account.getId()
<< ", Description=" << account.getDescription()
<< ", Balance=" << account.getBalance()
<< ", LastTransactionId=" << account.getLastTransactionId()
<< ", CustomerId=" << account.getCustomerId()
<< ')';
return out;
}
size_t hash_value(const Account& account)
{
return (size_t) account.getId();
}

As you can see, adding these functions is quite simple and does not require that the data object takes on any awareness of Coherence. Now it becomes possible to use Managed<Account> in our code:

// construct plain old Account object
Account account(32105, "checking", Money(7374, 10, "USD"), 55, 62409);
// construct managed key and value
Integer64::Handle hlKey = Integer64::create(32105);
Managed<Account>::Handle hAccount = Managed<Account>::create(account);
// cache hAccount
hCache->put(hlKey, hAccount);
// retrieve the cached value
Managed<Account>::View vResult = cast<Managed<Account>::View>( hCache->get(hlKey));
std::cout << "retrieved " << vResult << " from cache for key "
<< vResult->getId() << std::endl;
// convert the cached value back to a non-managed type
Account accountResult(*vResult);

This code demonstrates how a Managed<Account> instance is created from a non-managed Account data object.

The create method delegates to the copy constructor on the Account class—thus, the Managed<Account> instance is a copy of and retains no references to the Account instance it was constructed from. Managed<Account> is then inserted into the cache using its identifier as a key. Next, it is extracted from the cache. The NamedCache::get() operation returns an Object::Holder, which then must be dynamically cast back to the expected data object class. Finally, the Managed<Account> instance is used to construct a non-managed Account, which can be used by pre-existing application logic.

Note that it is certainly allowed for the application to use the Managed<Account> object directly, because all of Account's public methods are still accessible as is demonstrated when we call the getId method.

The requirement to address is serialization, which when using the Managed adapter is accomplished by implementing two additional free functions:

template<> void serialize<Account>(PofWriter::Handle hOut,
const Account& account)
{
hOut->writeInt64(0, account.getId());
hOut->writeString(1, account.getDescription());
hOut->writeObject(2, Managed<Money>::create( account.getBalance()));
hOut->writeInt64(3, account.getLastTransactionId());
hOut->writeInt64(4, account.getCustomerId());
}
template<> Account deserialize<Account>(PofReader::Handle hIn)
{
long long lId = hIn->readInt64(0);
std::string sDesc = hIn->readString(1);
Managed<Money>::View vBalance = cast<Managed<Money>::View>(
hIn->readObject(2));
long long lTransId = hIn->readInt64(3);
long long lCustomerId = hIn->readInt64(4);
return Account(lId, sDesc, *vBalance, lTransId, lCustomerId);
}

Notice that Account includes a data member Money, which is an instance of another plain old C++ class. To serialize this nested object, we simply write it out as a Managed<Money> object, applying the same patterns as were used for Managed<Account>. The serialization functions obviously have Coherence awareness, and thus it may not be desirable to declare them inside the same source file as that of the Account class. The sole requirement is that they are defined within some .cpp file and ultimately linked into your application. Interestingly, they do not need to appear in any header file, which means that they could be put into something like a standalone AccountSerializer.cpp file, without the need to modify the Account.hpp/cpp that is used in application code.

We must also register our serializable Managed<Account> class with the Coherence C++ library. This is accomplished via a simple call to a macro.

COH_REGISTER_MANAGED_CLASS(POF_TYPE_ACCOUNT, Account);

The registration statement specifies the POF type ID to class mapping. Unlike the Java and .NET versions, in C++, this mapping is performed at compilation time. The registration statement relies on the declaration of the serialization functions, and is therefore typically part of the same source file. Note the registration macro does not need to be called as part of the application logic—it is triggered automatically as part of static initialization.

The only thing missing now is the definition of POF_TYPE_ACCOUNT, which could just be a #define statement to the numeric POF type ID for the Account class. While you may just choose to embed the ID number directly in the registration line, it is recommended that #define, or some other external constant be used instead. Defining an external constant allows for the creation of a PofConfig.hpp file for the application that includes all the POF type IDs. This results in a single place to perform the ID assignment, so you do not have to search through the various data-object serialization files to adjust any of the IDs. Here is an example of this PofConfig.hpp file:

#ifndef POF_CONFIG_HPP
#define POF_CONFIG_HPP
#define POF_TYPE_ACCOUNT 1000
#define POF_TYPE_MONEY 1003
#define POF_TYPE_TRANSACTION 1004
#define POF_TYPE_TRANSACTION_ID 1005
#define POF_TYPE_TRANSACTION_TYPE 1006
#define POF_TYPE_DEPOSIT_PROCESSOR 1051
#define POF_TYPE_WITHDRAW_PROCESSOR 1050
#define POF_TYPE_CURRENCY 2000
#endif // POF_CONFIG_HPP

This header file is analogous to the pof-config.xml file we would have used in Java or .NET. With these last pieces in place, our example will now work with both local and remote caches, automatically being serialized as needed.

Perhaps, the strangest looking bit is the inheritance statement:

public cloneable_spec<Account>

This is part of the object model, and is called a "spec"-based class definition, where spec is short for specification. Specs do a fair amount of boiler-plate code injection to make the authoring of new managed classes easier than it would otherwise be. For instance, the following items (and more) are injected:

There is an entire family of specs. In the previous example, we used cloneable_spec because the item is going to be stored within a cache and needs to be cloneable. The other types of specs are:

All specs will automatically add inheritance from Object. Each will also add in some specific features of its own. Specs take the following template parameters:

spec<class, extends<parent>, implements<interface, ...> >

The arguments for the spec are:

The next related part is:

friend class factory<Account>;

This friend declaration allows the auto-generated create methods to access the protected constructors. It is the only bit of boiler-plate that specs cannot inject themselves.

Next, we can look at the data member declarations:

private:
const int64_t m_lId;
MemberView<String> m_sDescription;
MemberHandle<Money> m_balance;
int64_t m_lLastTransactionId;
const int64_t m_lCustomerId;

First we switch our long long data members to use int64_t. On most modern C++ compilers, long long is a 64-bit integer type, but it is not required to be of a specific size. The int64_t is a fixed-sized type, which is guaranteed to be 64 bits wide. It is part of a family of fixed-size types that exist on many systems—for those on which it does not, Coherence adds the definitions. By convention, managed types use fixed-size primitives, though this is not a requirement.

Next, we switch from std::string to a Coherence managed String, referenced by a View. The Money class is similarly overhauled, allowing us to reference it via Handle. You are not required to change these types—it is done here to improve serialization efficiency by avoiding the need to perform type conversion during serialization later on.

You'll also notice that, for String and Money, we used MemberView<String> and MemberHandle<Money> rather than nested String::View, and Money::Handle. This is done because the nested Handle/View/Holder smart pointer types are not thread-safe. As objects stored in a cache could be accessed by multiple threads, it is important that they internally be thread-safe. MemberHandle/View/Holder are thread-safe variants and should be used as data member references.

This doesn't mean you should avoid using the nested smart pointer types. In fact, they are what you will use most often. They are used as local variables and function/method parameters, basically anything that is stack allocated. Note that using the nested types for data members would have compiled and appeared to function just fine, but there would have been a memory leak/corruption looming. It is, therefore, highly recommended that you use the thread-safe variants for data members of all managed classes.

There are two additional thread-safe smart pointer variants included with Coherence C++:

The Final variants are similar in functionality to const MemberHandle/View/Holder, but include object model performance benefits based on the awareness that it is immutable. The Weak variants are used in conditions where your object graph includes cycles. As the object model makes use of reference counting, a cyclical graph would result in a memory leak. These "weak" smart pointers avoid the leak by automatically being NULL'ed out once they are the sole reference to an object, thus allowing the object to be collected. The use of these variants is otherwise identical to the Member variants.

Moving right along, we get to the constructors:

protected:
Account(int64_t lId, String::View sDesc, Money::View balance,
int64_t lLastTransId, int64_t lCustomerId)
: m_lId(lId), m_sDescription(self(), sDesc),
m_balance(self(), balance),
m_lLastTransactionId(lLastTransId),
m_lCustomerId(lCustomerId)
{
}
Account()
: m_lId(0), m_sDescription(self(), sDesc),
m_balance(self(), balance), m_lLastTransactionId(0),
m_lCustomerId(0)
{
}
Account(const Account& that)
: m_lId(lId), m_sDescription(self(), sDesc),
m_balance(self(), cast<Money::View>(balance->clone()),
m_lLastTransactionId(lLastTransId),
m_lCustomerId(lCustomerId)
{
}

First we notice that the constructors are now declared as protected, which blocks both stack-based as well as operator new-based allocations, leaving the static create method as the only allocation mechanism.

Next we see that MemberView and MemberHandle are initialized with self(). The thread-safe smart pointers take an optional second parameter, which is the object they are to reference, and if left out, defaults to NULL. The self() used in initialization is an easy pattern to follow, though perhaps a bit difficult to understand.

Each managed object contains an embedded micro read/write lock, which is used to provide the thread-safety to its smart pointer data members. The smart pointers thus require a reference to their enclosing object, and this is exactly what self() returns. Specifically, the self() method returns a reference to the base class of the managed object being created. It is conceptually similar to the this pointer, except that it references the fully initialized base class, while this refers to the partially initialized derived type.

Note that the thread-safe smart pointers can be used outside of managed classes as well. In this case, you will need to provide them a surrogate object that will protect them, as there is no self. This surrogate can either be an object you allocate yourself, or you can use one from a pool obtained by calling System::common().

The next change is that the methods are now all declared as virtual. This is certainly not required, but in general, managed classes are designed to operate like Java where all methods are virtual.

Finally, we override some standard methods declared by Object. These allow for hashing, equality testing, and printing of the object.

This was a bit of a detour, but finally, we can get back to making our class implement PortableObject. To do this, we'll simply modify the inheritance statement to indicate that this class implements PortableObject, and then implement its methods and register the type:

class Account
: public cloneable_spec<Account,
extends<Object>,
implements<PortableObject> >
{
...
// ----- PortableObject methods --------------------------------
public:
virtual void writeExternal(PofWriter::Handle hWriter) const
{
hWriter->writeInt64(0, getId());
hWriter->writeString(1, getDescription());
hWriter->writeObject(2, getBalance());
hWriter->writeInt64(3, getLastTransactionId());
hWriter->writeInt64(4, getCustomerId());
}
virtual void readExternal(PofReader::Handle hReader)
{
m_lId = hReader->readInt64(0, getId());
setDescription(hReader->readString(1));
setBalance(cast<Money::Handle>(hReader->readObject(2)));
setLastTransactionId(hReader->readInt64(3));
m_lCustomerId = hReader->readInt64(4);
}
};
COH_REGISTER_PORTABLE_CLASS( POF_TYPE_ACCOUNT, Account); // must be in .cpp

So after a lot of explanation, the act of making the class POF serializable is quite trivial. You will notice that in readExternal, we need to set two const data members, which is not allowable. This issue exists because PortableObject deserialization occurs after the object has already been instantiated. To achieve const-correctness, we would unfortunately need to either remove the const modifier from the declaration of these data members, or cast it away within readExternal.

The final serialization option available to us is to write an external serializer for our managed data object. Here we'll create one for the non-PortableObject version of the managed Account class. Note that the serializer-based solution does not exhibit the const data member issues we encountered with PortableObject.

class AccountSerializer
: public class_spec<AccountSerializer,
extends<Object>,
implements<PofSerializer> >
{
friend class factory<AccountSerializer>;
public:
virtual void serialize(PofWriter::Handle hWriter, Object::View v)
const
{
Account::View vAccount = cast<Account::View>(v);
hWriter->writeInt64(0, vAccount->getId());
hWriter->writeString(1, vAccount->getDescription());
hWriter->writeObject(2, vAccount->getBalance());
hWriter->writeInt64(3, vAccount->getLastTransactionId());
hWriter->writeInt64(4, vAccount->getCustomerId());
hWriter->writeRemainder(NULL); // mark end of object
}
virtual Object::Holder deserialize(PofReader::Handle hReader)
const
{
int64_t lId = hReader->readInt64(0);
String::View sDesc = hReader->readString(1);
Money::Handle hBalance = cast<Money::Handle>(
hReader->readObject(2));
int64_t lTransId = hReader->readInt64(3);
int64_t lCustomerId = hReader->readInt64(4);
hReader->readRemainder(); // read to end of object
return Account::create(lId, sDesc, hBalance, lTransId,
lCustomerId);
}
};
COH_REGISTER_POF_SERIALIZER(POF_TYPE_ACCOUNT,
TypedClass<Account>::create(),
AccountSerializer::create()); // must be in .cpp

All in all, this is pretty much the same as we'd done in Java, the prime difference being the COH_REGISTER statement that registers AccountSerializer and Account class with the Coherence library. The usage of the new managed Account class is somewhat more direct than with Managed<Account>:

// construct managed key and value
Account::Handle hAccount = Account::create(32105, "checking",
Money::create(7374, 10, "USD"), 55, 62409);
Integer64::Handle hlKey = Integer64::create(32105);
// cache hAccount
hCache->put(hlKey, hAccount);
// retrieve the cached value
Account::View vResult = cast<Account::View>(hCache->get(hlKey));
std::cout << "retrieved " << vResult << " from cache for key "
<< vResult->getId() << std::endl;

In later sections, we'll make use of specs to write other types of custom classes such as filters and aggregators.

Central to QueryMap is the concept of the ValueExtractor, which is used to extract an embedded value from a cached entry. For instance, you can use a value extractor to extract the balance from our Account data object.

These extractors are used both in expressing the filter criteria and in applying indexes to the cache in order to optimize query performance. Included with Coherence C++ is a ReflectionExtractor implementation, which is suitable for queries against remote caches, so long as the cache server contains a Java version of the data object:

hCache->addIndex(ReflectionExtractor::create("getBalance"), false, NULL);

ValueExtractor::View vExtractor = COH_TYPED_EXTRACTOR(Money::View, Account, getBalance);

ValueExtractor::View vExtractor =
COH_BOX_EXTRACTOR(Integer64::View, Account, getId);

ValueExtractor::View vExtractor = PofExtractor::create(typeid(Money), Account::BALANCE);

#define COH_PROPERTY_EXTRACTOR(TYPE, CLASS, PROPERTY) 
coherence::util::extractor::TypedExtractor< 
TYPE, CLASS, &CLASS::get##PROPERTY> 
::create(COH_TO_STRING("get" << #PROPERTY));

ValueExtractor::View vExtractor =
COH_PROPERTY_EXTRACTOR(Money::View, Account, Balance);

#define COH_MANAGED_PROPERTY_EXTRACTOR(TYPE, CLASS, PROPERTY) 
coherence::util::extractor::BoxExtractor< 
TYPE, CLASS, &CLASS::get##PROPERTY, 
coherence::lang::Managed<CLASS>::Holder> 
::create(COH_TO_STRING("get" << #PROPERTY));

ValueExtractor::View vExtractor =
COH_MANAGED_PROPERTY_EXTRACTOR(Money::View, Account, Balance);

Coherence C++ ships with the same built-in filter set as that provided for Java. These filters are capable of executing against both local and remote caches. When chaining together the built-in filters is not sufficient to express your query, you are free to also write custom filters. Unless the filters will only be targeted at a local cache, you will also need to produce a Java version, as that is what will actually do the filtering when running against a remote cache.

While the logic within Java and C++ implementations doesn't have to be identical, it is important that the implementations are compatible, which implies:

Now we can put all these things together and finally perform a query from within C++:

// add an index for the description property on the Account class
ValueExtractor::View vExtractor =
COH_PROPERTY_EXTRACTOR(String::View, Account, Description);
hCache->addIndex(vExtractor, false, NULL);
// query for all "checking" Accounts
Set::View vSetResult =
hCache->entrySet(LikeFilter::create(vExtractor, "checking%"));
// iterate the result set printing each matching entry
for (Iterator::Handle hIter = vSetResult->iterator(); hIter->hasNext(); )
{
Map::Entry::View vEntry = cast<Map::Entry::View>(hIter->next());
Account::View vAccount = cast<Account::View>(vEntry->getValue());
std::cout << vAccount << std::endl;
}

As you can see, performing the query and iterating the results is quite trivial. All the real work is in defining extractors and filters. Knowing how to implement custom extractors and filters is important, but keep in mind that you can get quite far with the built-in ones.

The following is a entry processor which can be used to deposit funds into our remote Account cache:

class DepositProcessor
: public class_spec<DepositProcessor,
extends<AbstractProcessor>,
implements<PortableObject> >
{
friend class factory<DepositProcessor>;
// ----- constructors --------------------------------------------
protected:
DepositProcessor()
: m_vMoney(self()), m_vsDescription(self())
{}
DepositProcessor(Managed<Money>::View vMoney, String::View vsDescription)
: m_vMoney(self(), vMoney), m_vsDescription(self(), vsDescription)
{}
// ----- InvocableMap::EntryProcessor interface ------------------
public:
virtual Object::Holder process( InvocableMap::Entry::Handle hEntry) const
{
COH_THROW (UnsupportedOperationException::create());
}
// ----- PortableObject interface --------------------------------
public:
virtual void readExternal(PofReader::Handle hIn)
{
initialize(m_vMoney, cast<Managed<Money>::View>( hIn->readObject(0)));
initialize(m_vsDescription, hIn->readString(1));
}
virtual void writeExternal(PofWriter::Handle hOut) const
{
hOut->writeObject(0, m_vMoney);
hOut->writeString(1, m_vsDescription);
}
// ----- data members --------------------------------------------
protected:
FinalView<Managed<Money> > m_vMoney;
FinalView<String> m_vsDescription;
};
COH_REGISTER_PORTABLE_CLASS(POF_TYPE_DEPOSIT_PROCESSOR, DepositProcessor);

As you can see, this stub implementation contains no processing logic. Its only purpose is to convey the operation type and state when serialized and transmitted to the Java cache servers, where the deserialized Java version will handle the processing work.

Aggregators will follow the same pattern of just being client-side state conveying stubs, and an example is omitted here due to their close similarity with the stub entry processor we've just presented.

Coherence C++ follows the Java-style observer pattern, and event registration is performed against methods declared as part of the ObservableMap interface.

class ObservableMap
: public interface_spec<ObservableMap,
implements<Map> >
{
public:
virtual void addKeyListener(MapListener::Handle hListener,
Object::View vKey, bool fLite);
virtual void removeKeyListener(MapListener::Handle hListener,
Object::View vKey);
virtual void addFilterListener(MapListener::Handle hListener,
Filter::View vFilter = NULL, bool fLite = false);
virtual void removeFilterListener( MapListener::Handle hListener,
Filter::View vFilter = NULL);
};

As you can see, the feature set is the same as that available in the Java version of ObservableMap, including key-and-filter based registrations, and the ability to request lite events. Lite events are free to omit the old and new values in order to avoid the additional resources required to carry them over the network.

When matching events occur, you are notified by a callback on the supplied custom MapListener implementation. The MapListener interface is again similar to the Java version, and the usage is the same as described in Chapter 7,

class MapListener
: public interface_spec<MapListener,
implements<EventListener> >
{
public:
virtual void entryInserted(MapEvent::View vEvent);
virtual void entryUpdated(MapEvent::View vEvent);
virtual void entryDeleted(MapEvent::View vEvent);
};

Let's put together a simple custom listener that prints cache changes to standard output:

class VerboseMapListener
: public class_spec<VerboseMapListener,
extends<Object>,
implements<MapListener> >
{
friend class factory<VerboseMapListener>;
public:
virtual void entryInserted(MapEvent::View vEvent)
{
std::cout << "inserted " << vEvent->getKey() << ", "
<< vEvent->getNewValue() << std::endl;
}
virtual void entryUpdated(MapEvent::View vEvent)
{
std::cout << "updated " << vEvent->getKey() << " from "
<< vEvent->getOldValue() << " to "
<< vEvent->getNewValue() << std::endl;
}
virtual void entryDeleted(MapEvent::View vEvent)
{
std::cout << "deleted " << vEvent->getKey() << std::endl;
}
};

Event listener registration is performed just as in Java:

hCache->addFilterListener(VerboseMapListener::create());

Event notifications occur locally on a dedicated event-dispatching thread associated with the cache. It is thus important to consider pushing any long running listener logic onto application threads so that subsequent events are not blocked or delayed.