In order to complete
SAK-9854 I had to analyze the BaseUserDirectoryService's use of the UserDirectoryProvider's "createUserRecord" method. It turned out not to be called in a way that matched the documentation, and theoretically could only be called under very unusual circumstances (the institution's provider would have to create user records on the fly when a new authentication ID showed up, but never before). I couldn't find any providers which enabled this feature, and after researching JIRA and the email archives, it seems clear that it resulted from a misunderstood feature request. (The same one addressed by SAK-9854, in fact.) As part of delivering SAK-9854, I'll drop this method from the interface.
While tracing through the code, I also found other apparently unused aspects of the interfaces. For example, "destroyAuthentication()" takes no action in the service or in any visible provider implementation. JLDAPDirectoryProvider's code comments "not sure what to do here". The interface's JavaDoc describes it as "for the current user / request", but the idea of a "current" user or request is awfully vague for a system-wide component. This may be an example of obsolete code or an early design idea that went nowhere.
Unused code represents an ongoing maintenance cost and a haven for bugs. However, I'd classify the problems as minor if they weren't also in the provider APIs. Unused methods in a provider interface represent an ongoing development cost for institutions worldwide as their programmers are required to understand and implement methods which do nothing.
After I make a survey of the code available to me and do some testing, I'll check changes into a branch and ask for review from the sakai-dev community. If there are no objections, we can then try to move the changes into the trunk for the next major release.