In this scenario the client wishes to create a new link to a requirement resource (or any externally managed resource identified with a URI) that the Architecture Management resource is on the source (subject) end. The client first GET’s the OSLC AM representation of the AM resource with its ETag value. It inserts a new RDF/XML element in the <oslc_am:Resource> element that represents the link, and PUTs back the entire contents of the resource to the provider. The service provider will notice the new element and interpret it as a new property to of the resource. The removal of editable elements in the document imply the deletion of that property.
Example 1. Create a simple link to a requirement
This scenario assumes that the service provider allows the insertion of links, and that the client user has the permissions to do so. The client has a URI reference to an AM resource ( https://am.acme.com/resources/res323), and a URI of the externally managed requirement resource ( https://reqserver.acme.com/requirements/req10). The client also knows what link type (predicate) to use ( http://acme.com/links/elaborates). The client could allow the user to select the link type from a list of known types on the AM service provider using the Link Type service.
1. The client GET’s the AM resource to insert a link into, and notes the ETag value.
Request
GET https://am.acme.com/resources/res323
Accept: application/x-oslc-am-resource+xml
Response
200 OK
Content-Type: application/x-oslc-am-resource+xml
ETag: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
rdf:about="https://acme.com/resources/res1">
<oslc_am:Resource>
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
</oslc_am:resource>
</rdf:RDF>
2. The client modifies the content, inserting a new link element into the body of the <oslc_am:Resource> to represent the link. The client then PUTs back the resource to the same URI with the current ETag value in the If-Match header. If the service provider permits the the insertion of link, the user has authorization, the syntax of the link is correct, the service provider will response with a 200 OK response.
Request
PUT https://am.acme.com/resources/res323
Content-Type: application/x-oslc-am-resource+xml
If-Match: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
xmlns:acme="http://acme.com/links/"
rdf:about="https://acme.com/resources/res1">
<oslc_am:Resource>
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
<acme:elaborates rdf:resource="https://reqserver.acme.com/requirements/req10"/>
</oslc_am:resource>
</rdf:RDF>
Response
200 OK
ETag: "_sownmds21sa92js6aloaa"
Example 2. Create a link to a requirement with properties
This scenario shows how a client can insert a link to a requirement, and associate an additional property to the link itself. This property, a short description, applies to the link. The scenario follows the same outline as adding a simple link (Example 1.), the only difference being the introduction of an additional <rdf:Description> element which augments the link property.
1.The client GET’s the AM resource to insert a link into, and notes the ETag value.
Request
GET https://am.acme.com/resources/res323
Accept: application/x-oslc-am-resource+xml
Response
200 OK
Content-Type: application/x-oslc-am-resource+xml
ETag: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
rdf:about="https://acme.com/resources/res1">
<oslc_am:Resource>
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
</oslc_am:resource>
</rdf:RDF>
2. The client modifies the content, inserting a new link element into the body of the <oslc_am:Resource> to represent the link. It also inserts a new <rdf:Description> element as a sibling to the <oslc_am:Resource> containing the property to associate with the link. An rdf:Id attribute is added to the link element so that it can be referenced within the resource, and this reference is used in the rdf:about attribute of the description element.
The client then PUTs back the resource to the same URI with the current ETag value in the If-Match header. If the service provider permits the the insertion of link, the user has authorization, the syntax of the link is correct, the service provider will response with a 200 OK response.
Request
PUT https://am.acme.com/resources/res323
Content-Type: application/x-oslc-am-resource+xml
If-Match: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
xmlns:acme="http://acme.com/links/"
xml:base="https://acme.com/resources/res1"
rdf:about="https://acme.com/resources/res1">
<oslc_am:Resource>
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
<acme:elaborates rdf:ID="id1" rdf:resource="https://reqserver.acme.com/requirements/req10"/>
</oslc_am:resource>
<rdf:Description rdf:about="#id1">
<dc:Description>This link is valid for all use cases</dc:Description>
</rdf:Description>
</rdf:RDF>
Response
200 OK
ETag: "_sownmds21sa92js6aloaa"
Example 3. Attempt to create a simple link with stale ETag
This scenario assumes that the service provider allows the insertion of links, and that the client user has the permissions to do so. The client has a URI reference to an AM resource ( https://am.acme.com/resources/res323), and a URI of the externally managed requirement resource ( https://reqserver.acme.com/requirements/req10). The client also knows what link type (predicate) to use ( http://acme.com/links/elaborates). The client could allow the user to select the link type from a list of known types on the AM service provider using the Link Type service.
In this scenario some other client changes the resource while this client is still modifiing the resource with the new link. The service provider returns a 409 response indicating that the ETag is stale. This client must perform the GET again to get the current ETag, however it might be appropriate to let the user know that the resource changed while working on it.
1. The client GET’s the AM resource to insert a link into, and notes the ETag value.
Request
GET https://am.acme.com/resources/res323
Accept: application/x-oslc-am-resource+xml
Response
200 OK
Content-Type: application/x-oslc-am-resource+xml
ETag: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
rdf:about="https://acme.com/resources/res1">
<oslc_am:Resource>
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
</oslc_am:resource>
</rdf:RDF>
2. Some other client has changed this resource after this client GETs the resource, and before it PUTs it back.
3. The client modifies the content, inserting a new link element into the body of the <oslc_am:Resource> to represent the link. The client then PUTs back the resource to the same URI with the current ETag value in the If-Match header.
Since the ETag is out of sync, the service provider returns a 409 response.
Request
PUT https://am.acme.com/resources/res323
Content-Type: application/x-oslc-am-resource+xml
If-Match: "_siemvnshyu2746sakalfuy"
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_am="http://open-services.net/xmlns/am/1.0/"
xmlns:acme="http://acme.com/links/"
rdf:about="https://acme.com/resources/res1">
<oslc_am:Resource>
<dc:title>ServiceInterface</dc:title>
<dc:description>This interface is used to do service things.</dc:description>
<dc:type rdf:resource="http://www.eclipse.org/uml2/3.0.0/UML/Interface" />
<dc:format>application/x-uml+xml</dc:format>
<acme:elaborates rdf:resource="https://reqserver.acme.com/requirements/req10"/>
</oslc_am:resource>
</rdf:RDF>
Response
409 Conflict
Content-Type: application/rdf+xml
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:oslc="http://open-services.net/xmlns/common/1.0/">
<oslc:Error>
<oslc:statusCode>409</oslc:statusCode>
<oslc:message>ETag mismatch. Most likely the resource was changed
while you we working with it.</oslc:message>
</oslc:Error>
</rdf:RDF>
