How to determine the Workspace/Stream and Component combination a Change Set was delivered to using OSLC / Rest / Plain Java?
I'm attempting to understand the relationships between workspaces/streams, components, and change sets, so I apologize in advance if this question is really just a misunderstanding on my part.
Background:
I have a project area that has multiple (10+) streams in its "Source Control" folder as seen in the RTC thick client. These streams all appear to re-use/reference a set of project scoped components, such as "Default Component" and "Test Scripts".
In the thick client, there's a menu bar option to Search -> Jazz Source Control -> Change Sets. In this search window, you can select both a component and a "location", which can be a workspace, stream, baseline, or "anywhere".
Request/Question:
I'm attempting to create a report for users of a single stream. They want the report data filtered down to Change Sets that they created/delivered to the "Default Component" as they see it for a "Change Sets Committed Per Day" report (and other similar reports). They currently accomplish this manually using the search option mentioned above while selecting their stream as the location and providing created after/before dates. I tested this and it appears to work (please correct me if I'm wrong).
However, I'm having trouble figuring out how to replicate the results of that search feature for data collection purposes. I've tried the OSLC / Rest interface, but I'm getting stuck because a Change Set has data about the component it applies to but the component doesn't appear to have any link to a "parent" stream. For reference, if I start with a work item reference ID, find its change set URI(s), and use the change set URI to find the component URI, that's as far as I appear to be able to go in terms of establishing a link:
jazz/oslc/workitems/214097/rtc_cm:com.ibm.team.filesystem.workitems.change_set.com.ibm.team.scm.ChangeSet
jazz/itemOid/com.ibm.team.scm.ChangeSet/_z6VXATD_ieO0dISRzVFGbQ?_mediaType=json
jazz/itemOid/com.ibm.team.scm.Component/_ouBTQE53ieCaGOtM6Ru5Tg?_mediaType=json
After researching things, my understanding is that a component (particularly a project scoped one?) can be "shared" across multiple workspaces/streams. A stream just appears to be a workspace with a "stream=true" flag set; I don't understand the implications of that flag, though. If I approach the problem from the stream side, I can see that all of the streams have the same itemOID for a given component. So, the following URI has a list of "component flows", just like the other workspace URIs that I checked, and they all refer back to the set of components (or at least, the URIs for the component flows match):
/itemOid/com.ibm.team.scm.Workspace/_TzEo0GZ3EeiDNpD_8MP-CA?_mediaType=json
So, my question: How can I determine what Stream/Component combination a change set originated in/exists in? How is the thick client search functionality working? Is it filtering based on some other mechanism behind the scenes, like baseline? Am I missing something obvious, like how the "contextID" applies in this case?
Having reached this point, I assume that either I'm approaching the problem incorrectly or that this is something that will need to be implemented using the RTC Plain Java client libraries. Admittedly, my approach so far is based on preexisting code and queries that are work item-centric, so it's entirely possible that I'm overlooking an easier approach. I'd appreciate any advice or guidance that can be provided.
One answer
The first point is that a component doesn't "belong" to any stream ... it is a self-contained object. Logically, a component contains a set of change sets. Change sets are then grouped into sequences called "change histories", where a particular change history defines a "configuration" of that component. A "baseline" of a component is logically just a name for a change history of that component that is/was of interest to someone. When a stream "contains" a given component, all that means is that the stream has a reference to a change history of that component (which is what you see, when you ask for the history of the component in that stream).
Now a given change set can belong to an arbitrary number of change histories, so when you ask "what streams is a given change set in", you are asking "what streams refer to a change history that contain that change set". That is what the "locate change set" operation is for (it is available from the GUI, from the command line, and from the Java API).
Now a given change set can belong to an arbitrary number of change histories, so when you ask "what streams is a given change set in", you are asking "what streams refer to a change history that contain that change set". That is what the "locate change set" operation is for (it is available from the GUI, from the command line, and from the Java API).
Comments
Thank you very much for the clarification.
To verify that I understand: when a change set is delivered, it is both added to the component's overall set of change sets as well as being added to the specific change history sequence being referenced by the stream that the delivering user is working in? Then, if a user in another stream that also references the component were to accept that change set at a later time, the change set would then also appear in the change history sequence in the second stream?
Having browsed the Plain Java API documentation, am I correct in stating that IWorksSpaceManager's "findWorkspacesContainingChangeSet" method would be my best bet? Assuming I already know the change set exists (perhaps by using "findChangeSets") and have confirmed the component it is associated with is the one I care about, retrieving a list of workspaces/streams and then checking it to confirm that a particular stream is in the list should solve my problem.
Having browsed the Plain Java API documentation, am I correct in stating that IWorksSpaceManager's "findWorkspacesContainingChangeSet" method would be my best bet? Assuming I already know the change set exists (perhaps by using "findChangeSets") and have confirmed the component it is associated with is the one I care about, retrieving a list of workspaces/streams and then checking it to confirm that a particular stream is in the list should solve my problem.
Yes, your description of the behavior of delivering and accepting change sets is correct.
WRT the API, I'll defer to our API experts, but what you describe sounds reasonable.
The 'Locate Change Sets' editor in Eclipse for example uses the following API:
Client-side API:
WorkspaceManager.locateChangeSets(
ILocateChangeSetsSearchCriteria scope,
IProgressMonitor monitor)
Server-side API:
IScmQueryService.findLocateChangeSets(
ILocateChangeSetsSearchCriteria scope,
IRepositoryProgressMonitorHandle repoMonitor)