ModeShape/modeshape — pull request #847 by rhauch (2013-06-04 21:09:43+00:00)
Title: MODE-1710 Completed support for connector-generated events 

_This pull-request supersedes the earlier [pull-request](https://github.com/ModeShape/modeshape/pull/839); all of that pull-request's commits were included in this pull-request (though they were rebased)._

Our events include paths of the nodes, including the old path if a node is moved. Connectors only know about paths within the tree they make available, and do not have any ability to access how the nodes in its tree are projected into the repository (and thus the paths of the projected nodes from repository clients' perspective). Therefore, a fair amount of work was needed to be able to map connector-specific paths (including for nodes that no longer exist) to repository paths. This was quite tricky:

* An external nodes (exposed by the connectors) may not be even included in the repository's projections
* An external node might be used in multiple projections in separate workspaces, which means a single event generated by the connector might need to be mapped into multiple workspace-specific repository events
* An external node that is moved within the connector's single tree of content may actually be moved across projections. In this case, one projection might see a "NODE_CREATED" event while another projection might see a "NODE_REMOVED" event.
* The mapping of external to internal paths is by itself complicated and a function of the (potentially changing) projections.
* Removing an external node might cause one or more projections (that are based solely upon that external node or its descendants) to become invalid and require the removal of those projections.

Additionally, the Connectors class was not threadsafe, so when projections changed (e.g., because the removal of an external node requires the removal of a projection, or because a projection is administratively added/removed/changed) the Connectors class could become corrupted or at least expose inconsistent views of the data. And because processing a series of events requires a consistent view of the path mappings, I needed to refactor the Connectors class to provide these transient, immutable snapshots.

Several tests were added or expanded to verify the behavior.