[dna-dev] Proposed changes to the repository connector commands

There are several known issues with the initial 0.2 design of the commands used in the repository connector framework. These are documented in https://jira.jboss.org/jira/browse/DNA-213. I've just attached to that defect a patch (for the "dna-graph" project) that adds a new package with a new design for these command classes (now called "requests"). Hopefully this design gets us closer to addressing the known issues. I'm looking for any and all feedback. (Serge, you said you'd take a look. :-) Just in case you're not familiar with the commands, basically this is the way the connectors work: a connector client (e.g., the JCR implementation) creates a command for each request they want to have processed by a connector. Multiple requests can be sent via a single call to the connector, so it's possible, for example, to create a graph of nodes all in one bulk call. We can do some interesting things with the commands/requests. First, we can batch them together (as I mentioned), or accumulated for delayed execution (e.g., when a transaction is committed). Second, we could preprocess them, if we want to enforce certain orders or if we want to optimize a bunch of commands. Third, they can be serialized, which will help with fault tolerance. A fourth benefit is that it gives us some flexibility for future changes. For example, we could introduce new commands without requiring that connectors "understand" them (if the new commands could be executed by default using other commands). This is where the CommandExecutor comes it ... it's an abstract class that defines methods for executing each type of command, and each connector "implements its behavior" by implementing an executor. Some of the core "execute" methods are abstract, meaning the connector is required to implement them. Other methods are optional. For example, executing a command to delete a set of children of a node can be implemented in the abstract class by creating a "DeleteBranchCommand" for each child. If a connector can implement this more efficiently, then it should probably override the default method. However, it wouldn't have to, and as long it implemented the core execute methods, it would still work. Now, we really don't want the commands to be exposed to clients, which is why we want to create a little API on top of the commands - this is what https://jira.jboss.org/jira/browse/DNA-215 is all about. Once we have this, the JCR implementation, sequencers, etc. could use this instead. Under the covers, the API would be creating commands and sending them to the connector (when needed). Okay, back to the issues. We found out late in 0.2 that the commands didn't do everything we needed them to do, and if we're going to fix them, we need to do it quickly. This is one of the reasons why we want 0.3 to be short - we want to get these changes out the door so that people can start writing connectors. Thus, https://jira.jboss.org/jira/browse/DNA-213 and https://jira.jboss.org/jira/browse/DNA-215 are two of the biggest and most critical issues for 0.3. (The other blocker issue is https://jira.jboss.org/jira/browse/DNA-217 , which has to do with cancellation.) Right now, I want to get the core commands/requests done and done correctly. We'll add others in the future - for example some for searching (e.g., via SQL, SPARQL, etc.). Please speak up if you have any questions or comments or suggestions! Best regards, Randall