Question

I’m trying to think of a naming convention that accurately conveys what’s going on within a class I’m designing. On a secondary note, I’m trying to decide between two almost-equivalent user APIs.

Here’s the situation:

I’m building a scientific application, where one of the central data structures has three phases: 1) accumulation, 2) analysis, and 3) query execution.

In my case, it’s a spatial modeling structure, internally using a KDTree to partition a collection of points in 3-dimensional space. Each point describes one or more attributes of the surrounding environment, with a certain level of confidence about the measurement itself.

After adding (a potentially large number of) measurements to the collection, the owner of the object will query it to obtain an interpolated measurement at a new data point somewhere within the applicable field.

The API will look something like this (the code is in Java, but that’s not really important; the code is divided into three sections, for clarity):

// SECTION 1: // Create the aggregation object, and get the zillion objects to insert... ContinuousScalarField field = new ContinuousScalarField(); Collection<Measurement> measurements = getMeasurementsFromSomewhere();  // SECTION 2: // Add all of the zillion objects to the aggregation object... // Each measurement contains its xyz location, the quantity being measured, // and a numeric value for the measurement. For example, something like // '68 degrees F, plus or minus 0.5, at point 1.23, 2.34, 3.45' foreach (Measurement m : measurements) {    field.add(m); }  // SECTION 3: // Now the user wants to ask the model questions about the interpolated // state of the model. For example, 'what's the interpolated temperature // at point (3, 4, 5) Point3d p = new Point3d(3, 4, 5); Measurement result = field.interpolateAt(p); 

For my particular problem domain, it will be possible to perform a small amount of incremental work (partitioning the points into a balanced KDTree) during SECTION 2.

And there will be a small amount of work (performing some linear interpolations) that can occur during SECTION 3.

But there’s a huge amount of work (constructing a kernel density estimator and performing a Fast Gauss Transform, using Taylor series and Hermite functions, but that’s totally beside the point) that must be performed between sections 2 and 3.

Sometimes in the past, I’ve just used lazy-evaluation to construct the data structures (in this case, it’d be on the first invocation of the ‘interpolateAt’ method), but then if the user calls the ‘field.add()’ method again, I have to completely discard those data structures and start over from scratch.

In other projects, I’ve required the user to explicitly call an ‘object.flip()’ method, to switch from ‘append mode’ into ‘query mode’. The nice this about a design like this is that the user has better control over the exact moment when the hard-core computation starts. But it can be a nuisance for the API consumer to keep track of the object’s current mode. And besides, in the standard use case, the caller never adds another value to the collection after starting to issue queries; data-aggregation almost always fully precedes query preparation.

How have you guys handled designing a data structure like this?

Do you prefer to let an object lazily perform its heavy-duty analysis, throwing away the intermediate data structures when new data comes into the collection? Or do you require the programmer to explicitly flip the data structure from from append-mode into query-mode?

And do you know of any naming convention for objects like this? Is there a pattern I’m not thinking of?

---

ON EDIT:

There seems to be some confusion and curiosity about the class I used in my example, named ‘ContinuousScalarField’.

You can get a pretty good idea for what I’m talking about by reading these wikipedia pages:

• http://en.wikipedia.org/wiki/Scalar_field

• http://en.wikipedia.org/wiki/Vector_field

Let’s say you wanted to create a topographical map (this is not my exact problem, but it’s conceptually very similar). So you take a thousand altitude measurements over an area of one square mile, but your survey equipment has a margin of error of plus-or-minus 10 meters in elevation.

Once you’ve gathered all the data points, you feed them into a model which not only interpolates the values, but also takes into account the error of each measurement.

To draw your topo map, you query the model for the elevation of each point where you want to draw a pixel.

As for the question of whether a single class should be responsible for both appending and handling queries, I’m not 100% sure, but I think so.

Here’s a similar example: HashMap and TreeMap classes allow objects to be both added and queried. There aren’t separate interfaces for adding and querying.

Both classes are also similar to my example, because the internal data structures have to be maintained on an ongoing basis in order to support the query mechanism. The HashMap class has to periodically allocate new memory, re-hash all objects, and move objects from the old memory to the new memory. A TreeMap has to continually maintain tree balance, using the red-black-tree data structure.

The only difference is that my class will perform optimally if it can perform all of its calculations once it knows the data set is closed.

Answer 1

I generally prefer to have an explicit change, rather than lazily recomputing the result. This approach makes the performance of the utility more predictable, and it reduces the amount of work I have to do to provide a good user experience. For example, if this occurs in a UI, where do I have to worry about popping up an hourglass, etc.? Which operations are going to block for a variable amount of time, and need to be performed in a background thread?

That said, rather than explicitly changing the state of one instance, I would recommend the Builder Pattern to produce a new object. For example, you might have an aggregator object that does a small amount of work as you add each sample. Then instead of your proposed void flip() method, I’d have a Interpolator interpolator() method that gets a copy of the current aggregation and performs all your heavy-duty math. Your interpolateAt method would be on this new Interpolator object.

If your usage patterns warrant, you could do simple caching by keeping a reference to the interpolator you create, and return it to multiple callers, only clearing it when the aggregator is modified.

This separation of responsibilities can help yield more maintainable and reusable object-oriented programs. An object that can return a Measurement at a requested Point is very abstract, and perhaps a lot of clients could use your Interpolator as one strategy implementing a more general interface.

---

I think that the analogy you added is misleading. Consider an alternative analogy:

Key[] data = new Key[...]; data[idx++] = new Key(...); /* Fast! */ ... Arrays.sort(data); /* Slow! */ ... boolean contains = Arrays.binarySearch(data, datum) >= 0; /* Fast! */ 

This can work like a set, and actually, it gives better performance than Set implementations (which are implemented with hash tables or balanced trees).

A balanced tree can be seen as an efficient implementation of insertion sort. After every insertion, the tree is in a sorted state. The predictable time requirements of a balanced tree are due to the fact the cost of sorting is spread over each insertion, rather than happening on some queries and not others.

The rehashing of hash tables does result in less consistent performance, and because of that, aren’t appropriate for certain applications (perhaps a real-time microcontroller). But even the rehashing operation depends only on the load factor of the table, not the pattern of insertion and query operations.

For your analogy to hold strictly, you would have to ‘sort’ (do the hairy math) your aggregator with each point you add. But it sounds like that would be cost prohibitive, and that leads to the builder or factory method patterns. This makes it clear to your clients when they need to be prepared for the lengthy ‘sort’ operation.