In this scenario the server performs a long running operation like a MDD transformation. The transformation creates and modifies resources on the server, and perhaps externally (i.e. in SCM). The client initiates the process with a request to create a certain type of resource. The client can then poll that resource for status.
The general outline of the scenario is captured in the following sequence diagram.
We are considering this as a general pattern for executing services, especially long running services on managed resources. The actual details of the resource properties are not important at this point, but are used below as part of an actual executable example.
Example
In this example the transformation happens on resources that the AM service provider manager (i.e. Entity resources), and produce source code and/or configuration files. These generated resources are placed in an SCM or on a filesystem. The transformation process updates each of the resources transformed, setting a property to point to the generated artifact as the most recently generated resource.
The transformation resource itself goes througha series of status (Initiated -> Processing -> [Completed Succesfully | Completed Unsuccessfully] ). This status is a property of the transformation resource.
The transformation can be canceled by DELETE ing it or perhaps the client can PUT and update to the resource with an action property to abort. jc: I prefer using PUT to change the state of the resource rather than deleting it. Because we don’t really want the resource to go away, just want to stop the process from continuing.
Some changes the service might reject (i.e. changing of parameter values mid way through transformation).
Resources
This scenario requires a separate resource type to represent the transformation (generation). Its properties both indicate the type of transformation but also any parameters for the transform. This example also requires a specialized AM resource to act as the source of the transformation.
Entity Generator Resource
Entity Generator Resource is a resource that represents and manages a long running transformation of Entities to source code.
- Name:
EntityGeneratorResource
- Type URI
http://open-services.net/ns/am#EntityGeneratorResource
| Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
| dcterms:title |
exactly-one |
unspecified |
String |
n/a |
n/a |
The name of this transformation. |
| dcterms:description |
zero-or-one |
unspecified |
String |
n/a |
n/a |
Descriptive text about the transformation. |
| oslc_am:status |
exactly-one |
true |
String |
n/a |
n/a |
The current status of this transformation. |
| oslc_am:entity |
one-or-more |
true |
Resource |
Reference |
oslc_am:EntityResource |
A reference to an Entity to include in the transformation. |
| oslc_am:path |
exactly-one |
true |
String |
n/a |
n/a |
A path relative to the service provider pointing where to place the generated resources. |
| oslc_am:startTime |
exactly-one |
true |
Date Time |
n/a |
n/a |
The time the service started the transformation process. This time may be different from the creation time of this resource. |
| oslc_am:completionTime |
exactly-one |
true |
Date Time |
n/a |
n/a |
The time the transformation completed. |
Entity Resource
Entity Resource is a model element resource that represents an Entity. It has simple properties (name/type) and can be transformed into source code.
- Name:
EntityResource
- Type URI
http://open-services.net/ns/am#EntityResource
| Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
| dcterms:title |
exactly-one |
unspecified |
String |
n/a |
n/a |
The name of this Entity. |
| dcterms:description |
zero-or-one |
unspecified |
String |
n/a |
n/a |
Descriptive text about the Entity. |
| oslc_am:entityProperty |
zero-or-one |
false |
Local Resource |
Inline |
oslc_am:EntityProperty |
A simple property of this entity |
| oslc_am:latestGeneratedEntity |
zero-or-one |
true |
String |
n/a |
n/a |
A path relative to the service provider pointing where the latest source to be generated from this entity is. |
Entity Property
Entity Property is a simple property on an Entity.
- Name:
EntityProperty
- Type URI
http://open-services.net/ns/am#EntityProperty
| Prefixed Name |
Occurs |
Read-only |
Value-type |
Representation |
Range |
Description |
| dcterms:title |
exactly-one |
false |
String |
n/a |
n/a |
The name of this property |
| dcterms:type |
exactly-one |
false |
String |
n/a |
n/a |
The type of this property. |
Issues
- Should transformations expect to work on immutable resources? Is this a requirement?
- How to abandon a long running task (DELETE, PUT)?
- Should we define a specific (general) Job resource?
- Locking? Transactions? Or are these implementation specific issues, not OSLC API issues?
- Don’t use official AM namespace for resource examples (create new one i.e. http://example.com/mdd# )
- Consider instead of 201-Created response on POST of transformation resource, it would probably make more sense to respond with 202-Accepted. (from Steve Speicher)
