From what it looks like, all of the methods directly declared in org.jboss.managed.api.ManagedObject are only relevant on the server side (i.e. for a Profile Service developer). Whereas, ManagedComponent contains all of the methods that a client/end-user would care about. If this really is the case, the profileservice public API really shouldn't contain the ManagedObject interface at all. Today, the ManagedDeployment interface, which is part of the public API, has a number of methods that return ManagedObjects, and it also has similar methods that return ManagedComponents. This seems confusing for client-side users of this API. They'll wonder what the difference is between the two sets of methods and which ones they're supposed to use (the answer I think being they should never use the methods that return ManagedObjects). The ManagedProperty interface also contains several methods that rederence ManagedObject.

I think ideally there should be two sets of APIs:

profileservice-api - this would contain only classes a client/end-user should use; these classes would also be used on the server side in most cases
profileservice-server-api - this would contain ManagedObject, the various PS annotations, and any other classes only a PS MO developer would use

However, if it's too late to make this change at this point, I think the Javadoc on all methods that use ManagedObjects should be updated with prominent notes that the methods are not intended for use by clients/end-users and that the ManagedComponent counterparts should be used instead.

Thoughts?