Positionssyntax

Jede Ressource hat eine Position, über die sie zu einem bestimmten Zeitpunkt eindeutig identifiziert werden kann. Die Position für dateibasierte Ressourcen wird in Form eines Dateipfadnamens ausgedrückt. Für eine serverseitige Ressource enthält die Position die Informationen, die für das Finden des Objekts erforderlich sind (z. B. die ID einer Datenbank in einer VOB).

Die Position der Ressource wird benötigt, wenn Ressourceninhalt gelesen oder geschrieben wird oder wenn Eigenschaften auf einem Server gelesen bzw. geschrieben werden.

Für Location-Objekte gilt Folgendes:

Das StpLocation-Objekt repräsentiert eine Ressourcenadresse und kann daher zum Konstruieren eines Ressourcenproxys (mit einer der Provider-Factory-Methoden für Ressourcenproxys) verwendet werden. Generell gilt, dass der aus einem Location-Objekt erstellte Ressourcenproxy denselben Typ wie die Zielressource des Location-Objekts haben muss. Der Typ der Zielressource eines Location-Objekts kann jedoch nicht immer allein anhand der Adressangabe bestimmt werden. Daher kann diese generelle Regel beim Konstruieren eines Proxys nicht immer umgesetzt werden.

Die Position aller Ressourcen hat ein festes Format, das genutzt werden kann, um Ressourcen-IDs zwischen Clientsitzungen auf dem Client zu speichern. Diese feste Position muss nicht die Position sein, die beim Erstellen der Ressource verwendet wurde. Der Server erstellt während der Ressourcenerstellung diese feste Position für den Benutzer. Sie ist immer als unveränderliche Eigenschaft der Ressource verfügbar. Das StpLocation-Objekt bietet Methoden für das Abrufen der Zeichenfolgendarstellung einer Position und für das Zurückstellen der analysierten Zeichenfolge an eine Position.

Eine StpLocation-Instanz repräsentiert eine Positionsangabe, die auf ihre Komponentenfelder hin analysiert wurde. Es gibt eine Reihe unterschiedlicher Formate oder Schemata, um die Position verschiedener Ressourcen als Zeichenfolge auszudrücken. Diese Schemata setzen sich aus einem oder mehreren der folgenden Felder zusammen: Domäne, Repository-Name, Namespace und Objektname. Das Namespace-Feld bestimmt, welches Schema verwendet wird.

Das Interface StpLocation stellt Methoden bereit, mit denen eine Positionsangabe auf ihre Bestandteile hin analysiert werden kann. Mit den verfügbaren Methoden können Rational-CM-API-Clients Positionsangaben des Benutzers untersuchen, um festzustellen, ob sie für den Zielkontext geeignet sind. Ausgehend von dieser Analyse kann ein Client die Abschnitte der Positionsangabe bereitstellen, die der Benutzer weglässt, wenn der Kontext diese fehlenden Abschnitte nicht eindeutig definiert.

Die Methode StpProvider.stpLocation() vereinfacht diesen Prozess, indem sie aus ihrem Parameter Namespace ein fehlendes Positionszeichenfolgenschema und aus dem vom Client für den Provider bezeichneten Standard-Repository ein fehlendes Repository einfügt. (Lesen Sie hierzu auch die Javadoc-Informationen zur Methode StpProvider.setDefaultRepository.)

Für Operationen, die ein vom Benutzer angegebenes Dateisystemartefakt erfordern, ist der Name eines Dateisystempfads zu einem Dateibereich im Arbeitsbereich ausreichend. Verwenden Sie für Operationen, die ein benutzerspezifisches Objekt eines anderen Typs erfordern (z. B. eine Aktivität, ein Projekt oder einen Datensatz) eine Syntax, die eine Position im dem allgemeinen vollständigen Format angibt, das die Identifizierung eines Objekts über dessen Namen ermöglicht:
<Domäne>.<Namespace>:<Objektname>@<Repository-Name>
Das folgende Beispiel impliziert die Standarddomäne:
"stream:mystream@projects" 
Software, die Positionsangaben versteht, kann das Weglassen mehrerer Felder erlauben. Beispiel:

Das Interface StpProvider stellt Methoden für die Erstellung einer StpLocation in Formaten wie USER_FRIENDLY_LOCATION und STABLE_LOCATION mit den Methoden userFriendlySelector und stableSelector bereit. Zum Interface StpResource gehören getStableLocation- und getUserFriendlyLocation-Methoden, die die Werte für die vom Proxy definierten Eigenschaften STABLE_LOCATION und USER_FRIENDLY_LOCATION zurückgeben. Falls für den Client eine Position in einem bestimmten Format erforderlich ist, sollte der Client die diesem Format entsprechende Ressourceneigenschaft und nicht StpLocation.stpLocation() verwenden.