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.
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:
-
The asset-task node describes a task for the asset in general.
-
The artifact-task node describes tasks for a specific artifact, and references that artifact using its
work artifact-id.
-
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
|