Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
COSMOS UG SML
COSMOS Wiki > COSMOS Document Plan > COSMOS Manual Guide
Contents
COSMOS User's Guide Service Modeling Language
Category: User's Guide
| Owner | David Whiteman |
| Bug # | 218871 |
| Due dates | Schedule |
Outline
Overview
This section covers how to use the Service Modeling Language (SML) tooling on the Eclipse SDK Platform.
Purpose
The purpose of the SML tooling is to view and edit SML-IF documents, and to validate the content of SML and SML-IF documents. The SML-IF tooling plug-in also provides export and import wizards that are integrated into the Eclipse SDK Platform.
- Export operation creates an SML-IF document from the repository
- Import operation parses an SML-IF document into individual separate SML model documents and stores them in the repository (which can be a workspace folder).
The export operation packages and validates a set of documents representing an SML model to be interchanged into a single XML=based document in a standard way. The set of documents to be interchanged is called the SML-IF document’s interchange set. The documents in the interchange set constitute the SML model being interchanged.
Note: During the import operation, there would normally be some loss of data when an SML-IF document is broken into its respective SML model units. For example, the aliases associated with a document or schematron rule binding are not preserved in SML model units. To preserve this information, a meta-data file is generated with every SML-IF document import.
The SML-IF validator helps to ensure an SML-IF document:
- Conforms to XML 1.0 (Second Edition)
- Conforms to Schematron rules bound to documents
- Is valid under the SML-IF and SML schemas
- Conforms to the SML-IF and SML specifications
The SML-IF specification defines the format for a single XML-based document that can be used to exchange SML models between other consumers of SML models.
Figure 1 shows the SML-IF editor open in the Eclipse SDK Platform.
The SML-IF tooling plug-in includes a multi-page editor that contains three tabs:
- Overview - The overview window displays general information about the SML-IF document.
- Documents – The documents window displays definitions, instances, logical representation, alias names and logical tree, and a source representation of the selected document section.
- Source view – Source view window shows the raw source of the SML-IF file, color coded with syntax highlighting.
Summary
SML is an important step to drive significant, cross-platform business modeling improvements for IT professionals and their business platforms. SML provides an industry-agreed foundation for model-based management. SML allows developers to build modeling information for applications, devices and services that can be used during all stages of applications or service lifecycle including configuration, problem, change and release management.
As a common modeling language, SML simplifies IT management in multi-vendor environments. This provides a way for information to be shared across diverse tools and applications. It reduces both the cost and complexity associated with delivering the levels of service and responsiveness businesses need from IT today.
The SML tooling provides an editor for an SML-IF document. The tool also provides the ability to import SML-IF document into a project and export SML model units to an SML-IF document. A SML-IF document packages the collection of SML documents to be interchanged as a single XML document. All exported SML-IF documents conform to the schema defined by the SML-IF specification.
Terms you should know
The following table contains some basic terms you should know to make using this documentation easier.
| Term | Definition |
|---|---|
| SML | Service Modeling Language (SML) is an XML-based specification that is used to model complex IT resources, services and systems, including their structure, constraints, policies and best practices. An SML model defines a consistent way for computer networks, applications, servers and other IT resources are described or modeled to assist businesses to manage their services that are built on these. The SML specification leverages Schematron and unique XML Schema extensions to implement these models. |
| SML-IF | Service Modeling Language – Interchange Format (SML-IF) defines an implementation-neutral interchange format that preserves the content and interrelationships among documents. |
| Definition | A definition is one of two types of documents supported by SML-IF. A definition document is used to describe the structure and constraints of the model |
|
Instance |
An instance is one of two types of documents supported by SML-IF. An instance document describes a model entity |
|
SML repository |
In the SML tooling, this is a flat-file based directory structure. Each file in the structure contains an SML document. The Import operation creates SML document files based on the top level resources found in an input SML-IF document. |
|
SML validation |
Validating an SML model in accordance with the SML specification |
|
SML-IF validation |
Validating an SML-IF document in accordance with the SML-Interchange Format specification |
|
Domain model |
The root of an SML-IF document. Contains a set of definition an instance documents |
SML resources
- W3C Architecture domain SML Working Group — http://www.w3.org/XML/SML/
- W3C Architecture domain SML Charter — http://www.w3.org/2007/03/SML_Charter.html
- W3C SML Version 1.0 submission — http://www.w3.org/Submission/sml/
- W3C SML Interchange Format Version 1.0 submission — http://www.w3.org/Submission/sml-if/
- Schematron - http://www.schematron.com/
- XML Schema - http://www.w3.org/XML/Schema
Opening an SML-IF document in an editor
The SML tooling provides an editor that allows you to view and edit an SML-IF file. There are two ways to open an SML-IF document in this editor:
- Select File > Open... from the menu bar, and choose the file from the file system
- Double click on an SML-IF file that exists in the Eclipse workspace
The SML-IF editor has three main sections:
To view a specific section, select one of the tabs located at the bottom of the editor.
Overview section
Figure 2. Overview window of the SML-IF editor
|
Field |
Required |
Description |
|---|---|---|
|
Name |
Yes |
Name field is the namespace for the SML-IF document. |
|
Version |
No |
Specifies the version level of the model. |
|
Display name |
No |
Descriptive name of the model intended for display. |
|
Base URI |
No |
The base Uniform Resource Identifier (URI) provides a simple and extensible means for identifying a resource. For example, the URL http://www.eclipse.org/ is a URI that identifies a resource. |
|
Description |
No |
This is a detailed textual description of a model. |
Table 1. List of General Information fields
Validate the entire document function
To validate the SML-IF document, click Validate the entire document. This function validates the entire SML-IF document and reports any errors in the Problems view of your workbench. See Validating an SML-IF document for more information on validation.
Import model into repository function
To import the SML-IF document, click Import model into repository. This function imports the SML resources represented in the SML-IF document into the SML repository. See Importing an SML-IF document for more information on importing.
Documents section
The SML-IF editor Documents window displays an SML-IF document's definition and instance elements and their aliases, with elements organized in a logical tree.
You can view a tree display of definition and instance documents, and change the aliases of an individual document by selecting a resource and clicking the Add or Remove button. You can also view the subset of the SML-IF file that defines a document or instance element by selecting that element in the tree view, and that element's source will be displayed in the XML Representation field.
Figure 3 shows the SML-IF editor Documents window for the file Valid.xml, with the Course1 instance selected.
Figure 3. Documents section of the SML-IF editor
|
Field |
Description |
|---|---|
|
Documents |
There are two types of documents that are supported by SML-IF:
|
|
Logical Representation |
There are two types of logical representations contained in an SML-IF document:
|
|
XML Representation |
XML source of the selected element |
Source section
The Source section of the editor is displayed by clicking the Source tab. The Source section displays the text content of the SML-IF document with color syntax highlighting as shown in Figure 5.
Figure 4. The Source section within the SML-IF editor
Validating an SML-IF document
An SML model is a set of inter-related XML documents. Each SML model contains a special subset of documents that describe the schema and rules governing the structure and content of the model's documents.
SML model validation is the process of verifying that all documents in a model are valid with respect to this special subset. The key contribution of SML to validation lies in its handling of inter-document constraints, which are layered on top of the single-document validation of XML Schema and Schematron.
To validate an SML-IF document:
- From the Navigator window, select a desired document to be validated.
- Do one of the following to Validate the document:
- Right-click the document and select Validate SML-IF
- Alternatively, open the file with the SML-IF editor, select the Overview tab and click Validate entire document as shown in Figure 5.
Figure 5. Validating a document in the SML-IF editor
All errors/warnings/information are reported in the problems view. If there is no warning, error or information to be displayed, then the following Validation Passed message dialog appears to notify you that the document is valid and well formed.
Figure 6. Validation passed message
If you have a validation problem, the errors are displayed in the Problems view as shown in Figure 7.
To view a validation error:
- Double-click an error/warning entry in the problems view to navigate to the Source section of the SML-IF editor and the appropriate line number that is in violation, if line number information is available for that entry.
- The line-number of the SML-IF document is marked with an error or warning icon.
- After resolving the error in the SML-IF document, save and re-validate the document
Figure 7. Problems view window
Importing an SML-IF document into the repository
Import operation divides an SML-IF document into individual separate SML model documents and stores them in a desired target repository. Remember that the SML repository is directory structure of flat files, each containing an SML resource.
The following import procedure is based on the assumption that you already have an SML-IF document.
|
Steps |
Figure |
Import instructions |
|---|---|---|
|
Step 1. |
8 |
Start the Import wizard using one of the following three methods:
|
|
Step 2. |
9 |
From the Import Select window:
|
|
Step 3. |
10 |
From the Import-Interchange Format window:
|
After the SML documents are created, refresh the Eclipse workspace to display the files in the Navigator.
Figure 8. Step 1 – Import option on the Overview window
Figure 9. Step 2 - Import window
Figure 10. Step 3 – Import-Interchange Format window
Exporting SML resources from the repository
The export operation creates an SML-IF document from an SML repository. The export operation is integrated with Eclipse’s export wizard under the Service Modeling Language category as shown in Figure 11.
An SML-IF document can be formed by selecting Export... from the context menu of one or more SML resources that appears under a project.
The following export procedure is based on the assumption that you already have an SML document. Use the export wizard to create an SML-IF document.
|
Steps |
Figure |
Export instructions |
|---|---|---|
|
Step 1. |
n/a |
To start the Export wizard:
|
|
Step 2. |
11 |
From the Export Select window:
|
|
Step 3. |
12 |
From the Export Interchange Format window:
|
|
Step 4. |
13 |
From the Export Interchange Format window, page 2. Specify aliases, if desired, for document and SML-IF identity information.
|
|
Step 5. |
14 |
(Optional) Add rule bindings to bind a named Schematron rule to an SML instance.
|
After the SML-IF document is created, open the document in the SML-IF editor to display the document source. See figure 15 for an example of an SML-IF document.
The following figures correspond with above Export instruction table.
Figure 11. Step 2 – Starting the Export wizard
Figure 12. Step 3 – Selecting the resources to export in the Export wizard
Figure 13. Step 4 – Specifying a documents aliases and identity information
Figure 14. Step 5 - Modify the content to bind a rule to a document
Figure 15 shows the contents of an exported SML-IF document.
Figure 15. Contents of the new SML-IF document