Top Link For Java Usage Experiences

Let this be a page for discussion of experiences using TopLink for Java.

<rant on>

At Traveller's Express / Money Gram, we have had a very negative experience with WebGain and TopLink for Java.

We're using version 3.5.2, with patches, in a three-tier J2EE information system. We're not using entity beans, and we're not using DomainObjectStateHolders or DataTransferObjects - instead we're serializing DomainObjects between the EJB VMs and the Web VMs. Consequently we're using UnitOfWorks "merge" API.

We have found that the merge API doesn't work too well with certain kinds of relationships and WeakIdentityMap?s. When we use the merge API in create and update use cases on objects participating in a bi-directional relationship, under the (Mapping Workbench default) SoftCacheWeakIdentityMap, TopLink doesn't execute certain SQL update statements that we expect to see, and allows it's cache's state to diverge from the database's state. One possible explanation is that the objects into which we want to merge changes are getting garbage-collected from the cache between reading them and later invoking the merge method; but we feel that represents an exceptional condition that TopLink should recover from or report to the invoker instead of dropping the updates on the floor. We've also seen containsObjectInIdentityMap() return true immediately prior to the merge invocation with no intervening GC activity, so we feel there are at least two defects in the product.

Furthermore, we've had an unbelievably negative experience dealing with WebGain's support department. We've sent them a JavaUnit test case demonstrating the misbehavior, and their response has been to refute that a problem exists, try to discredit the test case, and try to close the issue after giving us a sub-optimal workaround (see Todd's comments below about VM bloat under FullIdentityMaps?).

We've also experienced flaky behavior from the Mapping Workbench, and noticed release engineering problems with their manuals and JavaDoc being out-of-sync. In addition we've received mutually contradictory advice on how to use the product from the manuals, the support department, and a consultant of theirs that we engaged.

Overall, it has been a very painful and frustrating experience, especially given the amount of money we paid for the product. It has cost our project several weeks of schedule time and many man-weeks of effort.

Buyer beware.


<rant off>
Well said, Randy. It's, in fact, difficult to express the depth of hardship this product has caused us. There are three fronts that have affected us negatively: the graphical O/R mapping tool (Mapping Workbench), the actual software itself (Foundation Library), and the support of the WebGain organization.

Mapping Workbench-- This swing-oriented GUI was recently rewritten from AWT. As you can imagine, it has some ideosynchratic behaviors. Probably the most interesting thing for me to note is that this GUI utilizes TopLink itself to persist information to flat files. Hence when a project map becomes corrupted on exiting the application, I find that less-than amusing.

The actual map output that is utilized by your application (the Foundation Library), is output in either an XML file, or a Java class. We've been using the XML version. However, the mapping workbench does not *always* produce the XML the way you'd expect. So it's a good idea to check the output before utilizing it in your application.

Furthermore, the default caching policy in the Mapping Workbench is SoftCacheWeakIdentityMap. This does NOT work at all in our case and does not work in certain VMs that do not handle soft references 'correctly' (using WebGain's words). However, there is no information regarding this in the documentation.

The Mapping Workbench is truly a very flaky product at best--flaky is good for pie crusts!

Foundation Library-- As Randy stated above, we're using the "merge" API. Unfortunately, it seems to let updates slip by somehow and never updates the database when an object's state has changed. Of course, this is intermittent. Now, we have come to use a temporary work-around by utilizing the FullIdentityMap caching policy. However, now we suffer from VM bloat because we're caching the entire database. Good thing it's small thus far!

The Support Organization-- This is by far the most disturbing part of our experience with WebGain, and TopLink in particular. We've experienced a significant project slip because the organization cannot adequately answer our questions and/or solve our problem (short of the work-around mentioned above). Additionally, they are arrogant enough to not acknowledge the fact that there could be a bug in their product, but not offer any solution or suggestions on how we are using their product incorrectly.

If that wasn't frustrating enough, by providing them with a JavaUnit test case that faithfully duplicates the functionality of our application, they have the whole story, the big picture, the overall view of how our system works. This test case consistently demonstrates the problem. That implies there is either a problem with how we're using TopLink, or there is a bug in their software. They continue to say the test case is invalid--that it does not show anything.

I second Randy's comment above:

Buyer Beware!!!


As for the Mapping Workbench - I agree entirely. It is a good example of a poor Swing application. Its use of XML to store the definitions is also a good example of inappropriate use of XML. So don't use it. Although we use the new version of the TopLink API we have persisted with the old non-Java builder, and the very intuitive flat-file based storage of definitions - and using these we have no definition problems at all.

(However for my next project I will probably recommend building the mapping definitions by hand in bespoke Java code, using the builder purely as a tool to get a few clues as to syntax. Not because of any problems with the old builder, but because I almost always end up preferring the structure of bespoke code to generated code on maintenance and testability grounds.)

As for the problems with the merge function - well we have made minimal use of that and so I cannot really comment, but I will confirm that I have seen some evidence of gc-related problems with the soft-caching policy. The TopLink newsgroups seem to advocate the HardCacheWeakIdentityMap? as a good default choice. Or you could try not caching at all. It's a nicely designed API that makes switching between these policies very easy.

TopLink support used to be very good. I haven't needed it for a while, so I don't know how it has been since Webgain took over.

As you can tell, I'm a TopLink fan. I haven't properly evaluated the CocoBase product so cannot compare the two, but I would certainly recommend the standard TopLink product over bespoke development or the basic functions offered in CMP entity beans


Or you could try not caching at all

We did. In that scenario, TopLink gets itself into an infinite loop mapping objects that participate in a bi-directional relationship, resulting in a stack overflow exception. So that's a third defect in the product that we've experienced (a fourth is that we've seen TopLink issue SQL select statements to check for an object's existence, despite the fact that we've configured it to instead check the cache for existence). Plus you have no choice but to use caching if you want to use optimistic locking with timestamps.

Regarding Graham's suggestion not to use the Mapping Workbench, we've received similar advice from WebGain's support department on other matters - don't use the parts of the product that don't work - but that's hardly satisfactory.

I'm mainly disappointed because I want to be a TopLink fan too. TopLink has been around for a long time, was intelligently designed by Smalltalk programmers :-) and is very comprehensive in terms of addressing all the issues that you encounter in ObjectRelationalMapping. IMHO it's much more sophisticated than CocoBase. And it would be prohibitvely expensive to build, instead of buy, an equally comprehensive and sophisticated solution. What's disappointing is that while it is comprehensive and sophisticated, in our experience it has also been very fragile, and difficult to learn how to use correctly, and vended by a company (WebGain) that has plenty of room for improvement in the areas of customer relations, knowledge transfer, and quality assurance.


Clearly some have had bad experiences with TopLink and WebGain. I'm not sure it's appropriate to try and respond to particular technical issues - that sort of thing is probably better covered on the product newsgroups. They were inaccessible last time I tried - so I guess I have recently had a bad support experience too :-(.

But I will reiterate that my TopLinkForJavaUsageExperiences have generally been very positive. For us it has been satisfactory just not to use the things that don't work, especially the Mapping Workbench - because the core ObjectRelationalMapping has worked well.


Just another two-cents-worth:

Or you could try not caching at all

In addition to the issues Randy mentioned above, TOPLink requires the use of caching if you use advanced features like optimistic record locking, indirection, remote sessions, or units of work. Only the most simplistic application would enable someone to turn caching off. would be prohibitvely expensive to build, instead of buy, an equally comprehensive and sophisticated solution...

This may be a diversion point for me. It's very clear that TOPLink has a two-tier heritage and it certainly has been around a while to enable the O/R mapping lib to become robust. However, I'm not convinced (yet) that a three-tier architecture requires all the sophisticated features. Currently, I'm not convinced either direction, but given the amount of time and money spent on integrating TOPLink, I think a simple solution, developed in-house is the way to go. Sure, it might actually utilize embedded SQL, but wouldn't depend on third-party support. has been satisfactory just not to use the things that don't work, especially the Mapping Workbench...

I certainly understand this, and see it as an alternative. We could export a template Java class from the mapper and build the class up as we create our application. Perhaps this is the way to go. Constitutionally, though, I have some heartburn over this when we paid a considerable chunk of change for a product that touts its GUI mapping tool. Not that it's my money, but I've made promises based on how long it should take to map the DB in the mapper. Seems like our productivity should/could be better utilizing the GUI, since our application is growing and changing consistently under development.

--ToddFredrich the class up as we create our application...

This is pretty much what I intend to do next time - I'm hoping it will be quite a productive approach as long as we stick to OnceAndOnlyOnce in the code that creates the definitions. It will certainly be easier to test.


I recommended the use of TOPLink Foundation 3.6 on a major project for the U.S. navy, using the 3-tier API to integrate with a web-based front end (i.e. servlets, JSP, struts), so we had to use the merge-API for our updates. We didn't make use of EJBs, as they are unnecessary.

Our experiences were very positive. We didn't run into any major problems with merging & updates, but also we don't have very complex relationships between our objects (i.e. no bi-directionals), since it's a port from an old COBOL legacy model. The Mapping Workbench was adequate, but I already knew of its traditional problems so I tried to stay away from it except for initial modeling... the maintenance of the mappings was performed by hand in the Java project code.

The thing I've gathered about TOPLink in general, though, is that there are lots of subtle engineering issues that at some point or another have been thought of by the TOPLink team, but their resolutions and/or workarounds haven't made it into the documentation. The documentation uses pseudo-code a lot, and doesn't give you a lot of the feel for the nuances of the Expression Builder or the Report Builder APIs. Ditto for the optimistic-locking issues where one has to ensure they keep a version field in their client-side model to preserve the timestamp/version state in-between transactions. Another issue is mentioned above, the ability to force checking the cache before the database -- there are circumstances where it will work, and others where it won't. One has to be patient to figure out the different ways TOPLink responds to different scenarios... TOPLink is a productivity enhancer that eliminates unnecessary hand-crafted SQL code -- in my experience it's not a means to abstract an RDBMS as a place to throw your objects.


Yes I've also generally had positive experiences with TopLink. I found the main drawback is it's hard to learn and the docs (especially the older docs) don't give in-depth coverage of all the features. But once you figure out how to use it properly it's a great tool. I've saved tons of time using it.


It's been two years and one company since I started this page. My current company has had very reliable, positive results with TopLink. We're not using the UnitOfWork "merge" API (instead we've developed our own, DomainObject -level EditingCopy? and merge algorithms, about which I hope to be writing patterns soon). We have a DomainModel of some 800 classes mapped to a schema of some 300 tables. We've been running TopLink in production for over two years now with very reliable results, under loads of hundreds of concurrent users and HTTP requests per minute. The workbench occasionally drops a primary key mapping on us, and is sluggish with a project of our size, so we're planning to drop it and maintain all our mappings in Java code. But, in my experience, TopLink is still the best ObjectRelationalMapping solution available, and I am an advocate of it. --RandyStafford

That's good news, Randy. Thanks for the update. I wondered if, perhaps, the Oracle purchase might also help TopLink's success where I perceived failure before. The company I am currently on assignment with is looking at how MetaDataMapping? (or ObjectRelationalMapping) tools can reduce their maintenance load and boost throughput or efficiency. The tools have come a long way in sophistication and availability since I contributed here--in a therapeutic, tempestuous way. I'll take another look... --ToddFredrich

We are using TopLink for the past two years in a project. We are using multi-tier architecture and unitOfWork merge, deepMerge and SoftCacheWeakIdentityMap. We have used TopLink 3.5, 4.0, and 4.6 versions. We have not got any unsolvable problems. We could use it successfully without any problems. We're also using TopLink cache synchronization and that works fine too. -Maha.(
I think TopLink mapping capabilities are enormous: TopLink is the only true "meet-in-the-middle-compliant" O/R tool around --Antonio. <> (Who deleted the rest of this page with it).
I'm using toplink on my third project. It has treated me well. We tend to use the object model a lot. Our biggest problem comes when trying to get all our tests to run in a reasonable time.

We've developed an opensource library that allows you to run Toplink in memory (ToplinkInMemory). When you're running unit tests it can give you a 38x speed up over running againist a database. For those of you running Unit tests that take a long time against a database (e.g. HSQL , or Oracle), you can find it at:

- TedOgrady

See also: ObjectRelationalImpedanceMismatch, ObjectRelationalImpedanceMismatchDoesNotExist (oh yes it does)

View edit of November 21, 2014 or FindPage with title or text search