The Key Manager
The class KeyManager is used to handle the key specified. It must contain three public static functions with the following signature:
static KeyType GetKey(TargetType&);
static IlsBoolean Match(KeyType lhs, KeyType rhs);
static long Hash(KeyType key, int size);
Rogue Wave® Server does not create instances of this class.
The function KeyManager::GetKey finds the key associated with the target object passed as its argument. The return value KeyType is the key associated with the object passed to the function—IlsIdentifier in the previous example. The argument passed to the function is the target type—Flight in the example. In certain cases, Rogue Wave Server will automatically call this function by supplying any object it has selected. You must implement this function so that it returns the key matching the object arbitrarily passed as its argument. In the above example, we just had to return getIdentifier().
The object passed to the function KeyManager::GetKey does not necessarily have to contain the key as a data member, although it is usually the case. A function of that object does not necessarily have to return the key either. The application must simply be able to locate the key by means of that object—in a table, for example. Keys could be stored in a separate table and be accessed by a flight object. In this case, the key would be completely independent of the flight object. It would neither be a data member of the class Flight, nor would it be accessible by a call to one of its member functions.
The function KeyManager::Match compares two keys and returns IlsTrue if they are identical; otherwise, it returns IlsFalse. This function is called by Rogue Wave Server at specific moments. In the previous example, the function evaluates character strings for equality.
The function KeyManager::Hash is the most complex. In most cases, however, you will be able to reuse functions from the class IlsHashKeyManager of the Rogue Wave Server library to implement this function.
The implementation of set-relations is based on a hash code table that stores elements contained in a set. This hash code table is a C++ array and is thus indexed by integers whose value must be contained between 0 and the size of the table minus 1. The size of this table increases as new objects are added to the set. As we said earlier, Rogue Wave Server is able to retrieve the key corresponding to an object stored in a set using the function KeyManager::GetKey. In the same way, Rogue Wave Server must also be able to store this key in the C++ array, or in other words, it should be able to associate a key of a given type with an integer.
To help Rogue Wave Server perform this operation, you must define a function KeyManager::Hash that implements this association.
At specific moments, it is Rogue Wave Server that calls this function by passing the required parameters (a key and a size). The function must then return a long integer contained between 0 and size minus 1. This operation can prove rather tricky if the key is a character string, for example. To overcome this difficulty, Rogue Wave Server offers a set of predefined hash functions that apply to most of the commonly used types. These functions are static member functions of the class IlsHashKeyManager. The complete synopsis of this class is given in the Rogue Wave Server Reference Manual.
For example, to implement the key manager of the set-relation _flights, you just have to write:
class KeyManager
{
public:
// GetKey and Match
// ...
static long Hash(IlsIdentifier key, int size){
return IlsHashKeyManager::Hash(key,size);
}
};
The type IlsIdentifier will automatically convert to char* and the function IlsHashKeyManager::Hash (char*, int size) will be invoked.
Another solution, which is more sophisticated and yet easier to code, consists in deriving the class KeyManager from IlsHashKeyManager:
class KeyManager :
public IlsHashKeyManager
{
public:
// GetKey and Match
// ...
};
In this case, the function KeyManager::Hash will be called. This will cause the function IlsHashKeyManager::Hash to be invoked and the overloading to be resolved.
The class IlsHashKeyManager also contains a set of match functions that apply to most of the usual situations that may arise. Consequently, you do not have to declare this function in the class KeyManager either.
In our example, the class KeyManager could be summarized as:
class KeyManager: public IlsHashKeyManager
{
public:
static IlsIdentifier GetKey(Flight& flight){
return flight.getIdentifier(); } };
For each set-relation that you define, you have to declare a data member of type IlsSetContextList and two callbacks, setSetContext and unsetSetContext. These are documented in this section. Although we have chosen a particular case—the update of a key—to explain how they work, you should be aware that they must be declared each time you establish a set-relation even if you do not intend to update the related key.
Version 5.8
Copyright © 2014, Rogue Wave Software, Inc. All Rights Reserved.