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

[Randall Hauch]

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