Concept: Reusable Asset Specification
This concept describes the Reusable Asset Specification (RAS), which defines how Reusable Assets are stored, along with the metadata used to classify and describe their content.
Main Description

Reusable Asset Specification (RAS)

This is an OMG standard that was jointly produced with multiple companies. RAS describes the structure of information about an asset, and is generally captured in XMI/XML.

Introduction

There are many kinds of software development artifacts in many forms, and from many authors with varying styles. This increases the costs of discovering, comprehending, and reusing other authors' artifacts. Providing consistent artifact organization, structure, description, and packaging mitigates some of these costs through consistency and predictability.

The Reusable Asset Specification (RAS) describes an extensible way to organize software artifacts into assets for future reuse.

Additional information on RAS can be found at IBM developerWorks (http://www-130.ibm.com/developerworks/).

RAS Key Concepts

An asset is a collection of artifacts that provides a solution in one or more contexts, and which has variability points, or customization points, and instructions for usage. The asset may have relationships to other assets as well.

The asset is further described using meta-data, which provides some of the asset's packaging. There are several major sections specifying the asset including some main asset attributes such as the name, and version, and description. In addition, the asset can be classified through simple name and value descriptors and through the declaration of contexts, such as a specific development or deployment context, and so on. The asset has a payload which is the collection of artifacts providing a solution. These artifacts may have instructions for proper usage, and the asset can have a relationship to other assets. These elements describing the asset are capturing in XML, and serve as a manifest for the asset.

To support varying degrees of reuse formalities and process maturity in organizations, the sections described above for specifying an asset are largely optional. This means that even though RAS supports a broad, and possibly deep structure for specifying assets, only a few items are actually required. Required items include the asset's name and id, and the declaration of the asset type. Otherwise, all the other elements are considered optional, and support an evolutionary strategy to conducting asset-based development activities in your organization.

Just as there are many types of artifacts, there are many types of assets, with each type represented by a different RAS profile. As defined earlier, one asset may comprise many artifacts. The asset type is extensible to support customization for your particular needs. Your organization may define the contents of a component to be different than what another organization may do. This is accomplished through profiles, wherein the core structure of RAS is preserved but through which it may be extended.

The manifest file and artifacts combine to form the asset. The asset may be physically combined into a single file, such as a .ras file, which is Zip file format, or it may be unbundled. In both cases, the manifest file points to the relative location of all the artifacts that comprise the asset, regardless of the physical composition of the asset.

The remainder of this page describes these concepts in further detail.

RAS Profiles

A RAS profile describes the asset's type. RAS profiles are expressed as XML Schema files. Some organizations create their own profiles. IBM has produced multiple profiles, including the RAS Default Profile.

When an asset is created, an XML file is produced that is based on one of these schemas, or perhaps based on a custom profile that your organization has created.

The RAS Default Profile can be used to represent assets of any type. In practice, you may want to use this profile to do some initial asset packaging, and then determine any additions you may deem necessary. For information on how to define new RAS profiles, see Guideline: Extending the Reusable Asset Specification.

RAS Manifest File

There is one manifest file (an XML file) that is produced for each asset. The manifest file is an instance of the RAS profile XML schema file. Depending on your packaging strategy you may call these the same name, such as rasset.xml, or you may call the files something unique for each asset. RAS doesn't specify the naming strategy for these files.

Search engines and repositories can use the manifest file to discover the contents of an asset, its classification, its related assets, and so on. The manifest file may be included in an installation wizard, stored in a library with other assets, or included in a development environment. See the next section, RAS Archive File for more information on where the manifest should reside when an archive file is used.

RAS Archive File

The archive file is the file in which the asset is deployed. It is an archive of the asset directories and artifacts that contains the asset manifest file as well as the asset's contents zipped into a single file with a .ras extension.

When an archive file is used, the manifest file is placed in the asset's root directory, above the sub-directories of artifacts (in other words, at the top of the archive). All other artifacts are then placed in the proper sub-directory, and the RAS Manifest file should have the proper reference to those artifacts.

When an archive file is not used, the manifest file may be placed in any location, and may point to artifacts just about anywhere.

RAS Structure

There are several sections for specifying an asset, as shown in the following image, major schema nodes for the RAS Default profile, version 2.2.

Specifying an asset: classification, solution, usage, related assets.


Asset Node

The asset node includes the following attributes:

  • Name
  • ID 
  • Date
  • State
  • Version
  • Access Rights

The asset description is captured in the description node, which is a child to the asset node.

Profile

As described in the RAS Profiles section, a RAS profile specifies a particular type of asset. This includes identifying the kinds of artifacts that should be in an asset, as well as how the asset should be classified and used. For more information on asset types, see Concept: Reusable Asset.

The profile section describes the asset type. The asset's type history can also be tracked. This means that if your organization creates a custom profile, they will identify which RAS profile your custom profile derived from. This lineage is stored with the schema and goes along with the asset. One benefit of this is that tools may pick up an asset from other sources, and determine the ancestry of the schema that is used to represent, and deal appropriately, with the asset. This information may be useful to the Asset Consumer in helping them understand the asset.

The profile node has the following attributes:

  • Name
  • ID History
  • Version Major
  • Version Minor
  • Reference

Classification

The classification of an asset includes both context entries and descriptors.

Context entries describe the intended environment that the asset is expecting to be applied within. This includes contexts such as development context, deployment context, or business domain context. A key point about context entries is that they have an id, and that this id can be referenced if you are describing the tasks for installing an asset for a particular context.

Some possible contexts to consider capturing values in an asset include the following:

  • Deployment Context: Identifies the servers and runtime environment for which the asset is intended, such as WebSphere

  • Development Context: Identifies the development environment in which the asset is intended to be developed or extended

  • Domain Context: Identifies the business domain of the asset such as Insurance

  • Reuse Scope Context: Identifies organizationally where the asset is intended to be reused, such as, project team, department, and enterprise.

  • Test Context: Identifies the contexts in which the asset should be tested, such as load test, performance test, and functional test.

Example of a development context: Development tools and environment: WebSphere, XDE for Java Release 2, jdk 1.4, Win 2K, etc.

Descriptors are name/value pairs that provide general classification. Classification descriptors may be defined that are organization- or project-specific, or they may reflect very specific elements from an industry classification schema. They may contain values that are very general to very specific. For example, a descriptor may be a name/value pair of {keyword, web development}, or it may be more verbose such as {problem solved, deriving common structures for J2EE online applications and codifying them in architectural mechanisms and frameworks}. The asset classification descriptors that can be used for a project or organization should be documented in the reuse guidelines defined for that project or organization.

The complexity of an asset partially determines its ease of usability, and thus it is a very important piece of information to potential consumers of the asset. Therefore, metrics can be gathered and stored as part of the classification documentation of the asset.

There are no agreed upon metrics that quantify the complexity of an asset. However, the following can be used as indicators of an asset's complexity (some call these "reusability metrics"):

  • The McCabe Cyclomatic Complexity metric
  • The number of dependencies the asset has on external elements
  • The number of steps the user must follow in order to install and customize the asset
  • The number of variability points
  • The number of lines of code
  • The quality of the documentation
  • Feedback received from users that have applied (or attempted to apply) the asset

The measurements of some of these items can be automated such as complexity metrics, lines of code, etc. Other items must be measured manually such as asset dependencies, tasks to install and customize, documentation size and quality. In any case, these metrics are generally gathered after the asset artifacts have been harvested.

Solution

This section describe's the asset's payload (i.e., the solution that the asset's artifacts provide to a problem). The documentation in this section should focus more on the nature of the solution that the asset provides and less on how to use the asset which is covered by the Usage section. For the purpose of external documentation then, the description of the solution should be to support the scenarios of asset searching, browsing, and consumption. Certainly not all artifacts need to be listed in the documentation for these purposes.

This section contains the set of artifacts that comprise the asset's payload (i.e., the solution that the asset's artifacts provide to a problem). We recommend organizing the artifacts according to the RUP work product sets if you are using the Default Profile. Other profiles may require a different organization. In the RAS Default Profile version 2.0, the solution node has many artifacts. For each artifact, the following set of attributes can be captured:

  • Name
  • Type
  • Reference
  • ID 
  • Version
  • Digest Name
  • Digest Value
  • Access Rights

Within the solution node is the artifact node, which is used to reference the artifacts in an asset such as source code files, models, test scripts, and so on. There are several child nodes under the artifact node, one in particular is the variability point. This allows the asset producer (i.e., asset artifact developer or asset packager) to identify the locations within a artifact that should be customized or modified in some way by the asset consumer.

Usage

In this section the instructions for using the asset are provided. The instructions should describe how to use the asset for the different contexts listed in the Classification section. There may also be instructions for specific artifacts listed in the Solution section.

The usage section should also include instructions for providing values for the artifacts variability points. Variability points differ based on the type of artifacts. For example, you might have a use case document in the asset and it could contain one or more variability points in the document wherein the Asset Consumer needs to provide the name of the project, and the name of some actors, and so on. Whereas, another artifact in the same asset, such as a model might have some variability points wherein one or more classes must be extended. In addition, in the same asset, some source code might have some variability points wherein the Asset Consumer must make some modifications for the target environment.

The usage section can dramatically lower the cost of reuse by providing sufficient guidance on applying and customizing the asset.

In the RAS, task nodes are used to describe the steps to install and customize an asset. There are three kinds of task nodes:

  1. The asset-task node describes a task for the asset in general.
  2. The artifact-task node describes tasks for a specific artifact, and references that artifact using its work artifact-id.
  3. The context-task node describes tasks for a specific context, and references that context using the context-id.

For each task node, the following set of attributes can be captured:

  • ID 
  • Task
  • Reference
  • Role
  • Task Type

Some of the usage information may be automated using scripts and wizards, which are stored in the Solution section with the other asset artifacts.

Related Assets

This section describes the asset relationships to other assets. Often hyperlinks and other references are useful for the Asset Consumer to navigate to other assets from this point.

The following attributes can be captured for each relationship:

  • Name
  • Relationship Type
  • Asset ID 
  • Reference

Although RAS doesn't specify the values of the relationship-type attribute, there are several values to consider as recommended practice:

  • Aggregation: the asset "owns" the referenced asset.
    For example, if the asset is an architectural framework it could contain two components that plug some holes in the framework. In this context, the architectural framework is the aggregate (i.e., container) of the components.
  • Parent: the asset's parental context.
    This relationship is the inverse of the Aggregation relationship. If asset X aggregates (owns) asset Y, then asset X is the parent of asset Y.
    Using the above architectural framework example, where the framework is the aggregate of two components, the architectural framework is the parent (i.e., the container, the aggregate) of the components.
  • Similar: the asset is like another asset
    For example, some patterns say something: check out this other pattern which is similar to this one.
  • Dependency: the asset requires the services of another asset


More Information