RootReference

[prdoyle]

In recent work on #22 I've had an idea.

Background

Problems

There are two separate birds here we might be able to kill with one stone.

Problem 1: Plethora of reference creation methods

There are three different ways to create references right now:

1. Bosk.buildReferences
2. The Bosk reference factory methods
3. The various Reference.then methods

1 is recommended wherever it's applicable. 2 and 3 are meant for dynamic situations where the path isn't known at development time.

Given that most applications should be using 1 only, it seems odd that 2 and 3 are so prominent in the API, comprising fourteen methods in five classes (Bosk, Reference, and three Reference subtypes), while 1 is just one simple method.

It's also not clear in the design which methods are the fundamental "primary" ones and which are "helpers". It turns out Bosk.reference is the fundamental one, and the rest ultimately call that method.

It would be nice to have a clean design with just enough helpers to make things convenient for users.

Problem 2: Passing Bosk to DriverFactory

One of the things the Bosk class does is to act as a factory for Reference objects. This is ... okay I guess. The Bosk class has a lot of responsibilities, and is a bit of a god class, but it works ok in practice, so I've procrastinated on trying to get systematic about the reference factory functionality.

The one place where this is really weird is when we're calling the DriverFactory function in the Bosk constructor. We want drivers to be able to create references, so the DriverFactory accepts a Bosk object as an argument; however, at this point, the Bosk object is not yet fully initialized because its constructor is still running. Again, this works ok in practice, but it is a bit weird to hand someone an object that won't entirely work yet.

It would be nice to have a cleaner way to allow DriverFactory implementations to create references that does not involve passing them a half-baked Bosk object.

Side note: Specialized reference types

We already have several specialized Reference subtypes for convenience in certain cases:

• CatalogReference<E> is equivalent to Reference<Catalog<E>>
• ListingReference<E> is equivalent to Reference<Listing<E>>
• SideTableReference<K,V> is equivalent to Reference<SideTable<K,V>>

Each of these subtypes offers two conveniences:

1. a then method that doesn't throw InvalidTypeException, and
2. a set of bind methods that return the same subtype.

The intent is to eliminate unneeded catch (InvalidTypeException ...) code in situations where a type error is known to be impossible. (In a world with buildReferences, it's not clear this benefit is worth the complexity, but perhaps that is a question for another time.)

The idea

Create a new Reference subtype called RootReference representing the reference whose path is /. This object would be the canonical reference factory. All Bosk reference-creating methods, with the exception of rootReference, would move to the RootReference class, including buildReferences. The RootReference class would have then methods that accept Path objects, allowing arbitrary references to be created dynamically.

RootReference would act like our reference factory. The Bosk object itself wouldn't do this anymore.

Change DriverFactory to accept a RootReference instead of a Bosk.

Caveats

There are some downsides to removing the Bosk argument to DriverFactory:

• Driver factories would lose access to other Bosk functionality that they can currently use, like instanceID() or name().
• Drivers themselves would no longer have access to the Bosk object. It's unclear whether this is a bug or a feature.

[prdoyle]

I've added RootReference in #47. I'm still on the fence about changing the DriverFactory reference to take RootReference instead of Bosk though.

[prdoyle]

In #53 I inined the newly deprecated methods so they're not called anywhere in the Bosk codebase itself.

I'll ship a release with this change, so that users can pull in that release and inline the methods in their own code before upgrading to a version without them.

[prdoyle]

Alright, this was completed in #54 has shipped in version 0.0.94.