The .NET operational descriptor is a significantly trimmed-down version of the Java operational descriptor. Because most of the operational settings are cluster-related, they do not apply to the .NET client, so the only things you can configure in the .NET operational descriptor are the logger, default cache factory, and the network filters.

For details on how to configure the logger please refer to the Coherence User's Guide, as there are several options available, including the ability to use one of the popular open source logging frameworks, such as Log4Net, NLog, or Logging Application Block from the Microsoft Enterprise Library by the way of Common.Logging abstraction library.

If you want to use a custom implementation of the configurable cache factory you can specify it within the configurable-cache-factory-config element. However, this is a fairly advanced feature and more likely than not you will never need to use it.

That leaves us with the network filters as the last thing we can configure, so let's see how we can register the PasswordBasedEncryptionFilter we created earlier:

<coherence xmlns="http://schemas.tangosol.com/coherence">
<cluster-config>
<filters>
<filter>
<filter-name>symmetric-encryption</filter-name>
<filter-class>
PasswordBasedEncryptionFilter, Coherence.Encryption
</filter-class>
<init-params>
<init-param id="1">
<param-name>password</param-name>
<param-value>my!paSSwoRD</param-value>
</init-param>
</init-params>
</filter>
</filters>
</cluster-config>
<logging-config>
...
</logging-config>
</coherence>

As you can see, the filter registration is very similar to the one in Java. The only major differences are the namespace declaration within the root element and how the class name is specified. The former is simply the side effect of a switch from a DTD to an XML Schema-based validation, while the latter reflects the difference in class loading mechanisms in Java and .NET.

On a .NET client, you need to include the assembly name the class should be loaded from in addition to the fully qualified class name. In the previous example, PasswordBasedEncryptionFilter class will be loaded from the Coherence.Encryption assembly. This rule will apply whenever a class name needs to be specified in one of the configuration files for a .NET application.

As I mentioned earlier, you will only be able to configure a subset of the cache schemes on a .NET client, but this simply reflects the fact that not all of the cache schemes that are available within the cluster make sense on a Coherence*Extend client. For example, it doesn't make any sense to configure a replicated or partitioned scheme on the client.

The schemes that you can configure are local, near, and remote cache schemes, as well as the remote invocation service. We have already discussed how to configure each of these in the preceding sections, so let's just take a look at the sample .NET cache configuration file.

<cache-config xmlns="http://schemas.tangosol.com/cache">
<caching-scheme-mapping>
<cache-mapping>
<cache-name>*</cache-name>
<scheme-name>extend-tcp</scheme-name>
</cache-mapping>
</caching-scheme-mapping>
<caching-schemes>
<remote-cache-scheme>
<scheme-name>extend-tcp</scheme-name>
<service-name>ExtendTcpCacheService</service-name>
<initiator-config>
<tcp-initiator>
<remote-addresses>
<socket-address>
<address>localhost</address>
<port>9099</port>
</socket-address>
</remote-addresses>
<connect-timeout>30s</connect-timeout>
</tcp-initiator>
<outgoing-message-handler>
<heartbeat-interval>1s</heartbeat-interval>
<heartbeat-timeout>10s</heartbeat-timeout>
<request-timeout>30s</request-timeout>
</outgoing-message-handler>
<use-filters>
<filter-name>symmetric-encryption</filter-name>
</use-filters>
</initiator-config>
</remote-cache-scheme>
</caching-schemes>
</cache-config>

All of this should be familiar by now, aside from the namespace declaration for the root element, so we will not spend any more time discussing it.

Apart from the namespace declaration and the differences in how class names are specified, the POF configuration file is pretty much identical to the one in Java.

<pof-config xmlns="http://schemas.tangosol.com/pof">
<user-type-list>
<include>
assembly://Coherence/Tangosol.Config/coherence-pof-config.xml
</include>
<user-type>
<type-id>1000</type-id>
<class-name>
BankTerminal.Domain.Account, BankTerminal
</class-name>
</user-type>
<user-type>
<type-id>1001</type-id>
<class-name>
BankTerminal.Domain.Transaction, BankTerminal
</class-name>
</user-type>
</user-type-list>
</pof-config>

The important thing is that the type identifiers match the ones configured within the cluster, and that you include the standard coherence-pof-config.xml file, which contains definitions for all of the built-in Coherence types that are required either for the Extend protocol itself or for the Coherence API, such as built-in filters, extractors, and aggregators.

You have probably noticed that the include element's contents is somewhat different and are probably wondering what this assembly:// thing is all about, so it is a good time to discuss the resource loading mechanism in Coherence for .NET.

The ResourceLoader is responsible for loading resources using the appropriate IResource implementation based on the URI-like resource name. It uses the protocol component of the resource name to determine which IResource implementation should be used:

The assembly://Coherence/Tangosol.Config/coherence-pof-config.xml reference in our POF configuration file should make more sense now, but the knowledge of the resource abstraction and the resource loading mechanism will also come in handy in the next section, when we look into various approaches to .NET client configuration.

The convention-based configuration mechanism depends on files with well-known names being placed in the application directory, and works in both desktop and ASP.NET web applications. It is by far the easiest way to configure the Coherence for .NET client and should generally be preferred to other mechanisms.

In order to use it, you need to create the following files:

Coherence for .NET client library will automatically detect these files on startup and use them to configure itself, unless they are overridden using one of the following two mechanisms.

In some cases it might make sense to place configuration files in a shared directory on the network, or to use files with different names. For example, you might need to keep separate sets of configuration files for development, testing, and production.

If you need to do that, you will have to configure the Coherence for .Net client explicitly. This can be accomplished in two ways: either programmatically, which we will discuss in the next section, or using the standard .NET configuration mechanism, and specifying configuration file names within the App.config or Web.config file.

In order to achieve the latter, you need to register a custom configuration section handler within your main application configuration file, and add a coherence section to it:

<configuration>
<configSections>
<section name="coherence"
type="Tangosol.Config.CoherenceConfigHandler, Coherence"/>
</configSections>
<coherence>
<cache-factory-config>
Configcoherence-dev.xml
</cache-factory-config>
<cache-config>
Configcache-config-dev.xml
</cache-config>
<pof-config>
Configpof-config-dev.xml
</pof-config>
</coherence>
</configuration>

In the previous example, we are using custom file names and are loading them from a Config subdirectory within the main directory of our application.

The previous example will work fine for desktop applications, as the paths specified will be resolved by the FileResource, relative to the directory where the application executable is located.

However, in a web application the paths would be resolved relative to the request path, which may or may not be what you expected. To eliminate the guesswork and the possibility for error from the equation, you should always force resolution against the root directory of a web application by prefixing paths with a tilde character:

<coherence>
<cache-factory-config>
web://~/Config/coherence.xml
</cache-factory-config>
<cache-config>
web://~/Config/cache-config.xml
</cache-config>
<pof-config>
web://~/Config/pof-config.xml
</pof-config>
</coherence>

The usage of the web:// prefix in the previous code snippet is optional, because WebResource is the default in ASP.NET applications. That said, it is the best practice to specify it, in order to eliminate any guesswork on the part of an unsuspecting reader.

Finally, in some cases neither of the approaches previously mentioned will work. One of the common examples is a Microsoft Office add-in that depends on Coherence for .NET client library. The problem with an Office add-in is that in order to use the default configuration, you would have to place the configuration files within the directory where the actual Office application's executable is located, which is not very practical. You also don't have the option of specifying paths to configuration files explicitly, as there is no .NET configuration file to speak of.

Fortunately, the solution is quite simple—you can embed configuration files into your add-in's assembly, and configure Coherence client programmatically during add-in initialization:

const string baseUrl = "assembly://CoherenceRTD/CoherenceRTD.Config/";
CacheFactory.SetCacheFactoryConfig(baseUrl + "coherence.xml");
CacheFactory.SetCacheConfig(baseUrl + "cache-config.xml");
CacheFactory.SetPofConfig(baseUrl + "pof-config.xml");

In this example, we are loading the embedded resources coherence.xml, cache-config.xml, and pof-config.xml, from a CoherenceRTD.Config namespace in a CoherenceRTD assembly.

That concludes the section on Coherence for .NET client configuration. It's time to roll up the sleeves and write some real code.

Just as in Java, there are two possible approaches to making your objects portable. The first one is to implement the Tangosol.IO.POF.IPortableObject interface directly within your class:

public class Customer : IPortableObject
{
// ---- data members -------------------------------------
private long id;
private String name;
private DateTime dateOfBirth;
// ---- constructors -------------------------------------
public Customer()
{
// deserialization constructor
}
public Customer(long id, String name, DateTime dateOfBirth)
{
...
}
// ---- properties omitted for brevity -----------------
// ---- IPortableObject implementation -------------------
public virtual void ReadExternal(IPofReader reader)
{
id = reader.ReadInt64(0);
name = reader.ReadString(1);
dateOfBirth = reader.ReadDateTime(2);
}
public virtual void WriteExternal(IPofWriter writer)
{
writer.WriteInt64( 0, id);
writer.WriteString( 1, name);
writer.WriteDateTime(2, dateOf�Birth�);
}
// ---- Equals, GetHashCode and ToString (omitted) -------
}

As you can see, implementing IPortableObject directly is very straightforward, so let's move on to the second approach.

The second approach is to create a separate class that implements a Tangosol.IO.Pof.IPofSerializer interface and associate it with your data class within the POF context. To complete the EnumPofSerializer example from Chapter 4, Implementing Domain Objects, here is the implementation of its .NET counterpart:

public class EnumPofSerializer : IPofSerializer
{
public void Serialize(IPofWriter writer, object o)
{
if (o == null || !o.GetType().IsEnum)
{
throw new ArgumentException(
"EnumPofSerializer can only be used to serialize enum types.");
}
writer.WriteString(0, o.ToString());
writer.WriteRemainder(null);
}
public object Deserialize(IPofReader reader)
{
IPofContext pofContext = reader.PofContext;
Type enumType = pofContext.GetType(reader.UserTypeId);
if (!enumType.IsEnum)
{
throw new ArgumentException(
"EnumPofSerializer can only be used to deserialize enum types.");
}
object enumValue = Enum.Parse(enumType, reader.ReadString(0));
reader.ReadRemainder();
return enumValue;
}
}

Again, the previous code snippet should be very easy to follow and feel familiar if you remember everything you read about POF in Chapter 4.

With serialization out of the way and portable objects in the cache, let's see how we can run the queries from a .NET client.

Just as in Java, you need to use value extractors when defining your filters. All of the filters and value extractors described in Chapter 5, Querying the Data Grid, are present in Coherence for .NET as well, so you can use them just as easily as you would in Java.

However, there are a few important things you need to understand, especially if you will be writing your own IFilter or IValueExtractor implementations.

For one, filters and value extractors can execute either within the cluster or on the client, depending on the type of the cache they are used with. If you issue a query against a remote cache, the filter and any value extractors that are part of its state will be serialized and transmitted to the proxy server for execution. The proxy server will then deserialize the filter into the appropriate Java implementation and execute it against the cache servers.

On the other hand, filters that execute against a local or a continuous query cache (unless the CQC is used to cache only keys but not the values) will be evaluated directly on the client, as the scope of the query is well defined and all the objects are already present on the client. This can significantly improve performance and reduce the load on the cache servers.

However, in order for this to work, both the filters and value extractors must have parallel implementations in Java and .NET. The standard filters are all implemented this way, but if you implement your own you will have to ensure that the .NET and Java implementations match and that both are properly registered within the corresponding POF configuration files, using the same type identifier.

In the remainder of this section, we will implement in C# the PropertyExtractor and the StartsWithFilter we have already implemented in Java in Chapter 5. This should provide you with enough guidance to make the implementation of your own filters and extractors a breeze.

IValueExtractor ext = new ReflectionExtractor("Address");

IValueExtractor ext = new ReflectionExtractor("getAddress");

public class PropertyExtractor
: AbstractExtractor, IValueExtractor, IPortableObject
{
// ---- data members -------------------------------------
private const BindingFlags BINDING_FLAGS =
BindingFlags.Public
| BindingFlags.Instance
| BindingFlags.IgnoreCase;
private String m_propertyName;
[NonSerialized]
private PropertyInfo m_property;
// ---- constructors -------------------------------------
public PropertyExtractor()
{}
public PropertyExtractor(String propertyName)
: this(propertyName, VALUE)
{}
public PropertyExtractor(String propertyName, int target)
{
if (String.IsNullOrEmpty(propertyName))
{
throw new ArgumentNullException(
"propertyName", "Property name cannot be null");
}
m_propertyName = propertyName;
m_target = target;
}
// ---- IValueExtractor implementation -------------------
public override Object Extract(Object target)
{
if (target == null)
{
return null;
}
Type targetType = target.GetType();
try
{
PropertyInfo property = m_property;
if (property == null || property.DeclaringType != targetType)
{
m_property = property =
targetType.GetProperty(m_propertyName, BINDING_FLAGS);
}
return property.GetValue(target, null);
}
catch (Exception)
{
throw new Exception("Property " + m_propertyName +
" does not exist in the class " + targetType);
}
}
// ---- IPortableObject implementation -------------------
public void ReadExternal(IPofReader reader)
{
m_propertyName = reader.ReadString(0);
m_target = reader.ReadInt32( 1);
}
public void WriteExternal(IPofWriter writer)
{
writer.WriteString(0, m_propertyName);
writer.WriteInt32( 1, m_target);
}
// ---- Equals, GetHashCode and ToString omitted -------
}

Event handling is one of the areas that are significantly different in Java and .NET. While Java applications typically use classic Observer pattern and define listener interfaces, whose implementations can then be registered with the observed object, .NET promotes events to first-class language constructs and provides the ability to handle events by simply registering delegates with each individual event.

Both approaches have pros and cons. In Java, you are forced to implement all the methods defined by the listener interface even when you only care about one of them, which is why most listener interfaces also have matching abstract base classes that implement event handling methods as no-ops.

On the other hand, in situations when events are closely related and you are expected to handle all of them, the listener class nicely encapsulates all the logic related to event handling.

The situation in .NET is quite the opposite: it is easy to register for a single event, but if you care about multiple events you need to register for each one separately. In the latter case .NET code tends to be scattered across multiple delegate methods, which makes maintenance a bit more difficult.

Fortunately, the Coherence for .NET library supports both approaches. You can register to receive events "the Java way" using the Tangosol.Net.Cache.IObservableCache interface:

public interface IObservableCache : ICache
{
void AddCacheListener(ICacheListener listener);
void RemoveCacheListener(ICacheListener listener);
void AddCacheListener(ICacheListener listener,
Object key, bool isLite);
void RemoveCacheListener(ICacheListener listener,
Object key);
void AddCacheListener(ICacheListener listener,
IFilter filter, bool isLite);
void RemoveCacheListener(ICacheListener listener,
IFilter filter);
}

As you can see, all variants of Add/RemoveCacheListener methods accept an instance of the Tangosol.NetCache.ICacheListener interface, which is identical to the MapListener Java interface we discussed in Chapter 7, Processing Data Grid Events:

public interface ICacheListener
{
void EntryInserted(CacheEventArgs evt);
void EntryUpdated(CacheEventArgs evt);
void EntryDeleted(CacheEventArgs evt);
}

The usage mechanics of cache listeners are exactly the same as we discussed in Chapter 7, so we will not repeat the details here. The bottom line is that, just as in Java, you can register to receive the events for a particular object, a set of objects defined by the filter, or a cache as a whole.

However, the Coherence for .NET library also provides several helper classes that allow you to handle the events "the .NET way". The general-purpose one is Tangosol.Net.Cache. Support.DelegatingCacheListener, which defines the CacheEventHandler delegate and EntryInserted, EntryUpdated, and EntryDeleted events:

public delegate void CacheEventHandler(object sender,
CacheEventArgs args);
public class DelegatingCacheListener : ICacheListener
{
public virtual event CacheEventHandler EntryInserted;
public virtual event CacheEventHandler EntryUpdated;
public virtual event CacheEventHandler EntryDeleted;
...
}

The delegate handling the event will receive two arguments: a reference to a cache that an event occurred in as a sender argument, and the details about the event as an args argument. The latter contains all the information related to the event, such as entry key, as well as the old and new values for non-lite events.

This allows you to easily register for cache events without having to implement the listener interface yourself:

IObservableCache cache = CacheFactory.GetCache("accounts");
DelegatingCacheListener listener = new DelegatingCacheListener();
listener.EntryUpdated += AccountUpdated;
cache.AddCacheListener(listener);
private static void AccountUpdated(object sender,
CacheEventArgs args)
{
// handle event...
}

In addition to the DelegatingCacheListener, Coherence for .NET contains another, more specific ICacheListener implementation that allows you to achieve the same goal and a bit more.

One of the problems with cache events within Windows Forms applications is that all the events received by a client are raised on a background thread, which means that they need to be marshalled to the UI thread if you need to do anything UI-related within the event handlers.

Because one of the main reasons for receiving events in a desktop application is to update the user interface in real time, Coherence provides an ICacheListener implementation that marshals the events for you, in the form of the Tangosol.Net.Cache.Support.WindowsFormsCacheListener class.

All you need to do is to pass the form that the event listener is associated with to its constructor, and the WindowsFormsCacheListener will handle the rest. The code to register for events within the code-behind class for a form will typically look similar to the following:

WindowsFormsCacheListener listener =
new WindowsFormsCacheListener�(this);
listener.EntryUpdated += this.AccountUpdated;
cache.AddCacheListener(listener);
private void AccountUpdated(object sender, CacheEventArgs args)
{
// refresh account details on the UI
}

It is worth noting that event marshalling from a background to the UI thread is also required in Windows Presentation Foundation (WPF) applications, but it needs to be done in a slightly different way.

Unfortunately, as of Coherence 3.5 there is no built-in listener implementation that does that (primarily because it would create dependency on .NET 3.5), and it is out of the scope of this book to discuss how to create one. However, you can find a WpfCacheListener implementation in the sample application, in case you need it.

As we have seen in Chapter 7, a continuous query cache is very useful in all types of applications, as it allows you to bring a subset or even all of the data from a partitioned cache into a client process, while guaranteeing that locally cached data is never stale—as the data within the cluster changes, it is automatically updated within each instance of a continuous query cache as well.

However, a continuous query cache is particularly interesting when used within desktop applications, as it enables easy creation of highly dynamic user interfaces that are automatically updated as the data on a backend changes. Typical examples where this might be useful are trading desktops and logistic applications, but many other applications could benefit from a more dynamic user experience as well.

The reason this kind of functionality is easy to implement with a CQC is that in addition to keeping itself in sync with a back cache, CQC is also observable—as the data within it changes based on events received from a cluster, CQC raises its own events that client applications can listen to and update UI components appropriately.

We have discussed in Chapter 7 how instances of a continuous query cache are created and the various arguments you can specify to control its behavior. I will not repeat that here, as the mechanics are exactly the same—you simply create an instance of the Tangosol.Net.Cache.ContinuousQueryCache class, passing the target cache and a filter to use to its constructor.

Instead, in the remainder of this section we will focus on how you can bind CQC, or any other observable cache, to a Windows Forms DataGridView control. It is not as straightforward as I'd like, but fortunately it is not too difficult either.

Data binding with Windows Presentation Foundation (WPF)

We need to show real-time account and transaction information to bank employees using the BranchTerminal application, a .NET component of our multi-platform sample application.

We know that we can use CQC to create a live view of the data we are interested in on the client. However, we can't bind UI controls to the CQC directly. While we could bind controls to the Values property of a CQC, this property returns a static, point-in-time snapshot of the CQC contents.

WPF data binding supports dynamic update of UI controls only if the data source they are bound to implements appropriate notification interfaces and raises the change events these interfaces define. Individual objects need to implement the INotifyPropertyChanged interface and raise the PropertyChange event whenever one of their properties changes. Similarly, collections need to implement the INotifyCollectionChanged interface and raise the CollectionChanged event whenever an element is added, updated, or removed from a collection.

CQC does not (and it shouldn't) implement either of these interfaces, so you cannot bind controls to it directly. However, .NET provides the ObservableCollection class, which implements both of these interfaces and is a great source for data binding. So the only thing we need to do is to create an adapter that will expose CQC contents as an ObservableCollection.

Accounts class that does exactly what we need:

public class Accounts :
ObservableCollection<Account>, IDisposable
{
private readonly ContinuousQueryCache m_view;
public Accounts(DispatcherObject control)
{
WpfCacheListener listener = new WpfCacheListener(control);
listener.EntryDeleted += OnDelete;
listener.EntryInserted += OnAdd;
listener.EntryUpdated += OnUpdate;
INamedCache accounts = CacheFactory.GetCache("accounts");
m_view = new ContinuousQueryCache(accounts,
AlwaysFilter.Instance, listener);
}
public void OnAdd(object sender, CacheEventArgs evt)
{
Add((Account) evt.NewValue);
}
public void OnUpdate(object sender, CacheEventArgs evt)
{
int index = IndexOf((Account) evt.OldValue);
SetItem(index, (Account) evt.NewValue);
}
public void OnDelete(object sender, CacheEventArgs evt)
{
Remove((Account) evt.OldValue);
}
public void Dispose()
{
m_view.Release();
}
}

As you can see, our Accounts class extends ObservableCollection and uses CQC events internally to keep its contents in sync with the CQC it wraps.

There are two important things to notice:

1. We pass the listener that is responsible for keeping a contents of our adapter class in sync with CQC as a third argument to a CQC constructor. This allows us to capture all CQC events, including the ones resulting from initial CQC population.

2. The listener we use is an instance of WpfCacheListener. This ensures that all event handlers are invoked on the UI thread, which is necessary because the change event from the underlying ObservableCollection will be raised and handled on the same thread.

Now that we have an observable Accounts collection, we need to bind a ListView control on our application's main screen to it.

The first step is to expose it as a property within the window class that contains our ListView control. In the case of our sample application, this is AccountsWindow class:

public partial class AccountsWindow
{
private readonly Accounts m_accounts;
private readonly Transactions m_transactions;
public AccountsWindow()
{
try
{
m_accounts = new Accounts(this);
m_transactions = new Transactions(this);
InitializeComponent();
}
catch (Exception ex)
{
...
}
}
public Accounts Accounts
{
get { return m_accounts; }
}
...
}

As you can see, we are passing the window itself as an argument to the Accounts constructor, in order to provide a dispatcher object that WpfCacheListener should marshal events to.

The next step is to define the necessary data bindings within the XAML file for the AccountsWindow:

<Window
x:Class="Seovic.Samples.Bank.UI.AccountsWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:cm="clr-namespace:System.ComponentModel;assembly=WindowsBase"
DataContext="{Binding RelativeSource={RelativeSource Self}}"
Title="Accounts" Height="600" Width="800" WindowState="Maximized"
Unloaded="Window_Unloaded">
WPFusing, for data binding<Window.Resources>
<CollectionViewSource x:Key="AccountsViewSource"
Source="{Binding Accounts}">
<CollectionViewSource.GroupDescriptions>
<PropertyGroupDescription PropertyName="Customer.Name"/>
</CollectionViewSource.GroupDescriptions>
<CollectionViewSource.SortDescriptions>
<cm:SortDescription PropertyName="Customer.Name"
Direction="Ascending" />
<cm:SortDescription PropertyName="Description"
Direction="Ascending" />
</CollectionViewSource.SortDescriptions>
</CollectionViewSource>
</Window.Resources>
...
<ListView
ItemsSource="{Binding Source={StaticResource AccountsViewSource}}"
SelectionChanged="AccountList_SelectionChanged"
Grid.Row="1" Grid.Column="0" Name="AccountList"
Background="White">
...
</Window>

First we specify DataContext for the AccountsWindow to be the window itself. This allows us to access the Accounts property we exposed in the previous step.

That is exactly what we do in the following step by creating a CollectionViewSource that defines grouping and sort order for our data, and binding it to the Accounts property.

Finally, we specify CollectionViewSource as the item source for our ListView, which ensures that the items within the view are grouped and sorted properly, and automatically refreshed as the underlying Accounts collection changes.

When everything is said and done, the end result looks similar to the following screenshot:

You should ignore the fact that the random number generator wasn't very generous to Ivan and myself, and focus on the functionality.

When you click on the account on the left, the list of transactions on the right is updated based on the selected account and transaction period. Whether you post transactions from the .NET client, Java web application, or C++ command-line client, both the account balance and the list of transactions will be updated in real time.

Unfortunately, it is impossible to show that in print, but don't take my word for it—download the sample application and see for yourself.