Architecture Management: Diagram Resource Usage Scenarios

Diagrams are an integral part of architecture management resources. Many types of diagrams; UML Class, Sequence, Statechart, ER Diagrams, BPMN, etc. are expected to be managed by an OSLC AM service provider. Diagrams are special in sense they have a special representation form and media type; image/*. Most browsers are capable of rendering many image media types (png, jpg, svg, ...).

For Architectural diagram resources simply GETing them with an Accept header of a known media type (i.e. image/* or image/png) should result in the service provider responding with the diagram representation in that form. If the resource is not renerable or not available in the specific media type requested, it simply responds with a 415 Unsupported media type.

This document desribes the main usage scenarios of diagrams in an Architecture Management service provider.

Simple View

A client or user will receive a URI to a diagram resource. The user wants to view this resource as an image, ideally in a browser. By default entering in a resource URI in a browser and 'navigating' to it will request from the server a text/html representation. If the service provider provides HTML representations, the diagram may be rendered as a image, or the HTML representation might have a link to the image. This should be a <img> tag with the URI of the diagram resource. The browser will then make a call to the GET the resource again, this time with an Accept header that includes the preferred image types that it is capable of rendering.

Embed in external document

A user wishes to embed a diagram managed by an OSLC AM service provider in another document, possibly a static HMTL document, hosted by another server. For HTML documents the user can simply insert a <img> tag with the src attribute set to the diagram resource URI. Browsers will request this resource with the image media types that it is capable of rendering.

Click through navigation

A diagram often is composed of many other views or representations of other resources. The user may want to "zoom" in on or navigate to an alternate representation of one of the elements in a diagram. HTML has a <map> tag that allows the user to click in a specific area of an image, and the browser will navigate to that page. This scenario requires only HTML representations, and the service providers ability to construct use the <map> tag and provide HTML representations of the elements in the diagram.

A client may have a specialized diagram resource viewer that is capable of both rendering the diagram as an image, but also able to provide feedback on specific elements in the diagram. For example hover help, or click through navigation. For example a diagram may render and represent a number of other AM or other OSLC resources.

HTML <map> tag will allow users to clip through an image to another html page. This requires an HTML representation of the diagram (with HTML tags).

UI Preview Hovers

A non-HTML browser client may want to provide additional information to the user about the resources in a diagram. For example such a client might render images, and provide OSLC UI Preview pop up help over selected or hovered elements in the diagram. Other user guestures could get and display additional information about the resource that is represented in the diagram's views (elements or parts of the diagram image).

Layers

When a client requests a diagram rendering by making a GET call with an Accept header with some image type (i.e. image/png), it can use the oscl_am.layers query parameter to specify the ids of the layers to include in the rendering. By default all layers are rendered.

-- JimConallen - 24 May 2012