"Cool" is what comes into your mind while reading this lines? And while you have back in mind that CDO recently released the offline mode, euphoria let's you shiver anticipation about another fancy feature in CDO? But then a wreckful question destroys all your happiness and you ask yourself: "What is legacy in the context of CDO?"
Well, if so, let me get you out of this mess and explain what the legacy mode is about.
If you remember CDO's getting started you probably had noticed that you had to convert your model to CDO. This step adapts your genmodel and changes some generation relevant settings. The most important of these changes is that instead of directly inheriting from EObject your model classes will extend CDOObject, or to be more accurate - CDOObjectImpl. This conversion results into the flexibility and scalability CDO offers. If you like to know more about the internals read the CDO wiki page. Just to sum it up - after the conversion your model is CDO-ified, or in other words: CDO Native.
Well, although this conversion gives you full access to CDO, like lazy loading and unloading, some don't like to or just can't convert their models. To be honest, when I started developing Dawn I also found this conversion tedious, not understanding the real meaning of it. But in my defence - at this time I did not even know what EMF is about ;) And because this was also the time Eike still proclaimed that there is no need for an offline mode in CDO I think we both are even now. ;)
But back to the topic. What if you can't use a native CDO model? For example if you only have the generated binaries. Then the legacy mode comes to your support. When legacy support is activated it is now possible to use pure EMF objects (legacy objects in the context of CDO) with the CDO repository. This makes it now easy to share your model even if it is not converted. But keep in mind that the legacy approach leaves you with the given disadvantages concerning scalability. So if you need the maximum of scalability and performance on huge models, you should use the native mode. But for smaller models legacy performs well. It is even possible to store the objects in legacy, than convert your model and proceed with a more scalable und flexible resource.
Legacy is not only limited to generated classes. In fact you can use it with DynamicEObjects if you want to. Again, it is recommended to use native objects. And in the dynamic cases it makes even more sense be converting the model is done easily using CDOUtil.prepareDynamicEPackage(dynamicMapEPackage), because you do not need to regenerated your classes. But if you want to use DynamicEObjects on CDO, for what reason ever, you are free to do so.
That's it? Not by a long shot. With the legacy mode, if required, legacy and native objects can be used combined. If your native model needs to reference a model which cannot be converted or vice versa this is now possible with CDO.
You might wonder how legacy performs compared to the native approach. The Legacy Mode is slower, in most cases, because it is just a bridge between pure EMF and CDO. But the loss of performance is not that big and only applies to the client side. Legacy mode is completely transparent to the server. This makes it possible to convert legacy to native and vice versa as mentioned above. Have a look at the picture below. The graph shows some simple performance measurements between native and legacy. You can see that the difference between native and legacy it not that big.
One question remains. How to use this new fancy feature? In an early design legacy was adapted automatically to CDO. But this has a major drawback. People could forget converting there models to CDO. This fact alone would not be that troublesome. But imagine now that this user runs into an error with a stack trace which does not point directly to legacy, even if it was the root of the problem. In this case it could be hard work to hunt it down. That's why we made legacy support configurable. And by default it is turned off. This leaves legacy to the once who are aware of it.
To switch legacy support on or off you can refer to static methods in CDOUtil. This will influence the setting for newly created CDOViews. Note, that these methods are only setting the default behaviour for the current thread. So you must ensure that you set the flag for the right thread.
void CDOUtil.setLegacyModeDefault(boolean on)
The snippet below shows how legacy can be enabled or disabled.
CDOSession session = ...;
CDOTransaction transaction1 = session.openTransaction(); //this transaction is opened with no legacy support which is the default
CDOTransaction transaction2 = session.openTransaction(); //this transaction is opened with legacy support
CDOTransaction transaction3 = session.openTransaction(); //this transaction is opened with no legacy support again
Additionally you can ask your view whether legacy is enabled for it by using the following method.
CDOView view = ...;
boolean isLegacy = view.isLegacyModeEnabled();
Last but not least I would like to thank our sponsor who made it possible to spend a major effort on the development of the legacy mode.
Now, feel free to test it and give us a feedback if you like ;)