Details
Critical Description
The graph Request framework was designed to use Location objects to refer to nodes, but the CreateNodeRequest only allows a Location object for the new node (and not the parent).
A little background may be important. When working with nodes, it's often beneficial for connectors to have any source-specific information about the node included in the request. The Location class was designed to serve this purpose, and as such each Location may contain the Path of the node and/or identification properties (e.g., UUID, or a source-specific key). Since, the Request classes use Locations for their references to nodes, the Requests pass along any path or identification information along with the request. In general, clients start off only knowing the path (sometimes they instead know the UUID), and so the connector framework specifies that the Location objects that are inputs on the requests need not be complete, and that the connector is to include in the request's response the actual and complete location of any node. It's then recommended that when the client receives the response, they use the actual location.
The procedure for creating nodes always involves specifying where the new node is to be placed. In the CreateNodeRequest, this took the form of a Location specifying the path (and optionally additional identification properties). The parent was then inferred from the path, but the request doesn't contain a Location for the parent. In other words, the request carries no identification information for the parent, requiring that the connector locate the parent by path (which may more expensive than locating by the source-specific identification properties).
The CreateNodeRequest needs to be changed so that it includes a Location for the existing parent. The request could then represent the child with a mandatory name. (Note that this also would get around the previous constraint that the Location for the new child must have a path; with this new approach, the Location of the parent will include a path and/or the identification properties.)
It remains a question whether the CreateNodeRequest should be corrected (changed, thereby breaking backward compatibility of any connectors developed against 0.3), or be done through a new Request class. It should be noted that the current approach really doesn't work well, and that since we're still pre-1.0, we can maybe afford to correct the connector API.
