Working with the Design Studio Exchange Format

4 Working with the Design Studio Exchange Format

This chapter describes the Oracle Communications Service Catalog and Design - Design Studio Exchange Format, the Exchange Format data schemas, and the modeling patterns that facilitate custom extensions when working with the Design Studio Exchange Format.

About the Design Studio Exchange Format

The Design Studio Exchange Format is an XML document based on the data model defined for Design Studio projects. The XML document is generated by a project build.

The Exchange Format represents the output of Design Studio configuration in a published XML format, facilitates the exchange of solution modeling information between Design Studio and other systems or applications, and enables you to extend Design Studio functionality.

For example, you can use the Exchange Format when:

Driving a run-time engine, such as for the Calculate Technical Action or for the Design and Assign provider functions.
Driving a third-party application, such as when generating reports from a solution.
Synchronizing with another catalog, such as when refining a catalog external to Design Studio.
Generating Java code in a reference implementation, especially for an implementation that is repetitive or pattern-based.

The Exchange Format represents all entities, elements, and relationships in Design Studio, and is used to produce an XML file (ending in .studioModel) for every Design Studio entity type in a solution. Each entity type, such as Product, Customer Facing Service, and Order entities, has an XML schema that describes the content of the XML file that is produced for the entity type. The XML files are generated every time you run a full or incremental build. Design Studio saves the XML files in a project generated folder, which you can access from the Project Explorer view.

Note:

Design Studio generates Exchange Format XML files for a sealed project during the initial import if the sealed project directory does not contain any .studioModel XML files in the project generated folder. Design Studio does not update the generated folder XML files for sealed projects during subsequent builds.

Before distributing sealed projects, Oracle recommends that you generate the project Exchange Format XML files to reduce initial build times when team members import the sealed projects.

The XML output that is generated from the Exchange Format is the same as the XML input used in the Design Studio reporting framework. Report designers can use the Exchange Format XML files to design custom reports. See "Working with Reports" for more information.

You can leverage the Exchange Format information by referencing the published XML format and data schemas, or you can use the Design Studio Model Java API to access the information in the Exchange Format. The Design Studio Model Java API is a wrapper that reads the Exchange Format XML files produced by Design Studio. When combined with other public Eclipse APIs, the Design Studio Model Java API enables you to extend Design Studio with custom functionality and features. For example, you can use the Design Studio Model Java API to add a new action to a Design Studio menu. See "Working with Design Studio Model Java API" for more information.

You can leverage the Exchange Format information when working with:

XML technologies, such as XQuery, XSLT, JavaScript, Java, and so forth
The Java model API
Action command extensions
Eclipse Builder and Packager extensions
Other Eclipse extensions

About the Exchange Format Model Lifecycle

Figure 4-1 illustrates the Exchange Format model lifecycle, which includes the following phases:

Design: You define data models in a project in Design Studio.
Generate: You produce the Exchange Format by building the project.
Consume: You use the Exchange Format to extend Design Studio or to integrate with external systems.

Figure 4-1 Exchange Format Lifecycle

Description of "Figure 4-1 Exchange Format Lifecycle"

When integrating with third-party applications, you can:

Add commands to Design Studio menus, which can be invoked to read the Exchange Format and run the integration logic necessary to propagate the model to an external system. Using action commands enables you to interactively invoke custom logic while designing a solution, such as validating an XQuery path provided in the solution design.
Add Model Processors to Design Studio, which run as background processes when you build a project. Model Processors can consume the Exchange Format and integrate with external systems. Using Model Processors enables you to embed custom logic in the solution design and to invoke that logic while building or compiling the solution. For example, you can generate custom artifacts or validate third-party components.

Additionally, external systems can interact with custom Design Studio extensions to access the Java Model API, from which the external system can consume the Exchange Format. Also, external systems can use the Java Model API or the XML files directly to consume the Exchange Format.

About the Exchange Format Architecture

Figure 4-2 illustrates the Exchange Format architecture:

The Action Commands, Model Processor, and three Custom blocks represent architecturally distinct components that provide custom logic using the Exchange Format XML or using the Design Studio Model Java API.
The Exchange Format block represents the fundamental definition of the Exchange Format (using XML technologies). The Model Locator Service block and the set of Model blocks directly under the Model Locator Service block represent the parts of the Java API which provide simplified access to the Exchange Format XML.
The Eclipse Extensions block represents the metadata that describes extensions to the Eclipse platform and to Design Studio. Typically, the extensions are supported by Java implementations. The Action Commands, Model Processor, and Custom Java code represent the Java implementation supporting those extensions.
The Custom block built on the Design Studio Java API (represented by the Model Locator Service block and the set of Model blocks directly under the Model Locator Service block) represents a custom Java implementation built independently of the Eclipse platform and of the Design Studio features.
The Custom block noted as Other and built directly on the Exchange Format represents an implementation that utilizes the Exchange Format XML directly. This type of custom implementation may use XML transformation technologies (such as XQuery and XSLT) and represents any integration with the Design Studio platform for which you elect to use the Exchange Format.

Figure 4-2 Exchange Format Architecture

Description of "Figure 4-2 Exchange Format Architecture"

About the Design Studio Model Schemas

Design Studio includes schemas that describe the XML files generated from the published Exchange Format. These schemas are bundled in a schemas folder in the Design Studio Report Design example and in the Design Studio Action Command example.

If, after you add the examples to your workspace, you move these schemas to a new location, ensure that you copy and move the full set of schemas in the schemas folder, as these schemas have dependencies defined among them.

You can review the details of the full Design Studio model by opening and reviewing the Design Studio schemas (you can also review the model by browsing the Design Studio Model Java API). For example, you can browse the schemas to review details about named attributes, named lists, and cardinality.

Viewing the Design Studio Schemas

You can review the details of the full Design Studio model by viewing the Design Studio schemas.

Note:

To view the Design Studio schemas, you must first add the Design Studio Report Design example or the Design Studio Action Command example to your workspace. See "Adding the Report Design Example to the Workspace" or "Adding the Design Studio Action Command Example to a Workspace" for more information.

To view the Design Studio schemas:

In Design Studio, switch to the Java perspective.
Click the Package Explorer tab.

The Package Explorer view becomes active.
Do one of the following:
- Expand the design.studio.example.action.command folder.
- Expand the design.studio.example.report.designs folder.
Expand the schemas folder.
Double-click one of the schema files to open the file in the Data Schema editor.

About the Design Studio Exchange Format Model

The Design Studio Exchange Format represents all entities, elements, and relationships in the Design Studio model. The information in the following sections describe model patterns that are useful when designing reports and when extending Design Studio with custom functionality.

Element Attributes and Children

The Design Studio Exchange Format includes XML elements named <element>, and these elements are called base elements.

All base elements in the Exchange Format model include the following base attributes:

@id (unique locator)
@name
@type
@typeName
@kind (Project, Entity, Element)
@path

Base elements also define the following child elements:

displayName (localizedString)
Note (localizedString)

A localizedString is a string value with an @lang attribute. The @lang attribute defines the related language. You use the @lang value default to define the default string value.

Example 4-1 Element Base Attributes and Children

<element
    id=“"
    name=“"
    type=“"
    typeName=“"
    kind=“"
    path=“">
 
    <note
       lang=“en-ca">
    </note>
 
    <displayName
       lang=“default">
    </displayName>
 
</element>

Entity Attributes and Children

You can extend entities to add additional children. Entity base attributes include all base element attributes, and the following:

@resource
extends (relationSingle)
project (relationSingle)

Element Lists

Child elements are contained in a list even when there is only one occurrence. The content of an element list is always an element. The elements in the list are usually of the same type. Mixing element types in a list is supported as well, and the element type attribute can be used to filter for specific element types when the list includes mixed types.

Nested entity and elements have the following modeling pattern:

Example 4-2 Element Lists

<element…>
   <elementList1 …>
      <element…>
         <elementList2 …>
            <element…/>
         </elementList2>
         <elementList3 …>
            <element…/>
         </elementList3>
      </element>
   </elementList1>
</element>

For nested elements, parent element details exist two levels up from the current element.

Element list cardinality indicates whether an element list is mandatory or optional. For zero or more elements, the element container is defined with a 0..1 cardinality. For zero or one elements, the element container element is defined with a 1..1 cardinality. Lists will always contain at least one element.

In Table 4-1:

Overall cardinality is the effective combined cardinality of the list element and its child elements.
The list element cardinality represents the first level of containment and indicates whether the list element is required or optional. List elements are elements with a specific type of child element. There is, at most, one occurrence of a list element in a parent element.
The child element cardinality indicates the number of instances of a child element that can appear in the list element. The child element is an instance of a standard element and its type is appropriate for the list element in which it is contained. An instance of a list element will always contain at least one child element. If the list is empty, the list element is not present.

Table 4-1 Element List Cardinality

Overall Cardinality	List Element Cardinality	Child Element Cardinality
0..1	0..1 (Optional)	1..1
1..1	1..1 (Required)	1..1
0..*	0..1 (Optional)	1..*
1..*	1..1 (Required)	1..*

Relation Attributes

The target and inEntity attributes provide contextual information from the target entity or element.

The inEntity attribute is optional. This element appears only when the relation is to an element (the kind attribute is defined as Element).

Relation attributes include the following:

@ref (represents an entity or element ID)

@type

@name

@kind (Project, Entity, Element)
target

@name

@typeName
inEntity

@name

@typeName

Example 4-3 Relation Attributes

<relation
    ref=“"
    type=“"
    name=“"
    kind=“">
 
    <target
        name=“"
        typeName=“"/>
 
    <inEntity
        name=“"
        typeName=“"/>
 
</relation>

Named Relation Lists

Lists of named relations can appear in elements and entities. A list can be optional or required and can contain one or more relations. The objects that can be referenced by a list are projects, entities, and elements.

Each relation list is typed as:

relationSingle: This list has one child defined as type relation.
relationMultiple: This list has multiple children defined as type relation.

The relation list cardinality defines whether the relation list is mandatory or optional. For zero or more relations, the relation container element is defined with 0..1 cardinality and with the type relationMultiple. For zero or one relations, the relation container element is defined with a 0..1 cardinality and with a type of relationSingle. Lists always contain at least one element.

Example 4-4 Named Relation Lists

<entity …>
   <relationList1 …>
      <relation…/>
   </relationList1>
 
   <relationList2 …>
      <relation…/>
      <relation…/>
   </relationList2>
   
   <elementList1 …>
      <element…>
         <relationList3 …>
            <relation…/>
         </relationList3>
      </element>
   </elementList1>
</entity>