Introduction

Metadata repositories are an important part of enterprise solutions. This article series shows you how to integrate repositories with your applications, share assets between repositories, discover and tap into new assets, and use a business glossary to classify metadata from a variety of sources. Part 1 focuses on how to enable asset-based development by integrating your applications with Rational Asset Manager (hereafter referred to as Asset Manager). Subsequent articles cover Tivoli® Application Dependency Discovery Manager, WebSphere® Service Registry and Repository, and WebSphere Business Glossary.

Asset-based development (ABD) is a key mechanism for addressing the ever-increasing challenges in the cost and efficiency of software production and delivery. Asset Manager is an asset management solution for collaborative software development. It supports creating, describing, and managing assets based on the Reusable Asset Specification (RAS), an industry standard from the Object Management Group (OMG). Asset Manager also provides asset searching, change tracking, and life cycle management, which facilitate the reuse of all types of software development assets. This article discusses how to use the Web service and HTTP APIs to integrate Asset Manager into cross-platform applications. Using these APIs, ABD can be enabled in a variety of software development environment to:

• Create and modify an asset
• Access the run time metadata of an asset
• Access the system metadata needed by the ABD process
• Interact with the asset governance process

See the Download section at the bottom of the article for the sample code used in this article.

Assets, ABD and Asset Manager

Today’s information systems are growing huge and complex. Customers want to maximize their investments when facing emerging business opportunities; solution providers want to reuse productions from previous work, to increase the quality while decreasing the cost of delivery. ABD can benefit both sides by reusing previous solutions (so-called assets) to solve recurring and emerging problems. This can reduce the duplication of investment, time, and labor.

The ABD process contains four key stages: asset identification, asset production, asset management, and asset consumption. Solutions that have been identified as potential assets move forward into production. The outcomes of the asset production are stored and managed in a repository as assets and reused by consumers. The consumers can also provide feedback into the asset production and asset management stages, which helps the ABD process become a self-improving loop.

IBM provides a suite of products for building an ABD process, including Rational Software Architect, Rational Clear Case/Clear Quest, and Asset Manager for asset production, consumption and management.

Asset Manager is the asset management and governance solution in the suite, and plays the central role in the ABD process. In addition to asset management, it provides a collaboration mechanism for asset reuse, an ontology system for better asset categorization, and a governance process for the asset life cycle. Applications need to interact with Asset Manager to participate in the ABD process.

Solution background

Asset Manager provides two types of user interfaces (UIs). One is a native Web-based UI and the other is the Asset Manager Rich Client plug-in embedded into Eclipse-based development tools (for example, Rational Software Architect or WebSphere Business Modeler). The plug-in provides a seamless integration with Asset Manager. However, a real development environment often contains a variety of development and management tools on different platforms, and users may already be familiar with their own operation styles and UIs. Currently, if you use tools that are not Eclipse-based, you must use Asset Manager’s Web UI to interact with the ABD Process.

Asset Manager also provides APIs for integrating Asset Manager into other applications. One is a Java-based binary API (see the Asset Manager InfoCenter in Resources for details on this API and guidance for integration). However, this API is a platform-specific implementation, and other non-Java based platforms such as the Microsoft® .NET Framework cannot benefit from this API. The other is a Web service and HTTP API, which can be used in a cross-platform environment, but is somewhat more complex.

This article discusses how to use the standard Web service calls and HTTP requests together to integrate Asset Manager into an application. Although the solution is demonstrated in Java, it can also be applied to other platforms.

Asset Manager content model

The Asset Manager content model contains two kinds of data: asset data (data related to a certain asset instance) and system metadata (data shared among the asset instances). Figure 2 illustrates the Asset Manager content model.

The asset data contains basic asset information, an asset manifest, the extended metadata, and the asset content (Figure 3).

The basic asset information contains:

• The asset ID and asset version, which uniquely identify an asset
• The date of the last modification on the asset
• The governance state of the asset
• The name and short description of the asset

The asset manifest is the core metadata; it follows the RAS and contains the following sections:

• Classification section — a set of descriptors for classifying the asset and a description of the contexts for which the asset is relevant.
• Solution section — an index of the collection of the artifacts which describes the hierarchical structure of the artifacts in the asset.
• Usage section — the rules for installing, customizing, and using the asset.
• Related assets section — this asset’s relationship to other assets.

The extended metadata is defined by Asset Manager to improve the user experience and facilitate asset reuse. This metadata contains:

• User Tags — user-defined descriptive information about the assets, which is in addition to the classification section of the asset manifest.
• Change History — a log of changes to the asset, which can be used for asset version and governance state tracking.
• Usage Metrics — some statistics information about users’ rating on the asset, as a popularity measurement of the asset. Metrics are useful for promoting reuse of the asset.

The asset content is the implementation of the solution. It contains a set of artifacts organized in a directory hierarchy. The hierarchical structure is in line with the solution section in the asset manifest.

The system metadata is the necessary common metadata shared by all the asset instances in Asset Manager. It contains the asset types, category schemas, governance schemas, and relationship types. It is also important information when manipulating the asset.

The following sections discuss how to access the information of the Asset Manager content model.

Connect to the Web service and HTTP APIs

Asset Manager provides two APIs: Web service and HTTP. The Web service API can access the system metadata and asset manifest, but cannot create and update the manifest and content of the asset. The HTTP API can retrieve, create, and update the content of the asset, but cannot manipulate the extended metadata of the asset and the system metadata. A successful ABD integration must combine the capabilities of both APIs.

First, you must connect to the APIs. Both APIs use HTTP Basic Authentication for identifying users. Therefore, before a request is sent, make sure that the username and password are set correctly in the HTTP request head.

The HTTP API uses HTTP GET requests for retrieving the content of the assets, and HTTP POST requests for creating and updating the content of the assets. The endpoint for the HTTP API is:

https://<host>:<port>/com.ibm.ram.repository.web.ws.was/RAMSecure/
RAMAssetAccess.jsp?assetID=<id>&version=<version>

Be aware that this is an HTTPS connection — you must make sure the security connection parameters, such as the key store and trust store, are set correctly for a successful request.

To connect to the Web service API, do the following:

• Download the Web Services Definition Language (WSDL) file of the Asset Manager Web service (see the Asset Manager InfoCenter in Resources).
• Use a code generator, such as WSDL2Java, to generate the stubs to the remote service.
• Perform a Web service request to the address:

  http://<host>:<port>/com.ibm.ram.repository.web.ws.was/RAMSecure/services/RAM1

  
  

Once you are connected, you can access the Web service by using the operations defined in the WSDL. On other platforms, such as .NET or C++, you can use the similar techniques to connect to the HTTP and Web service APIs.

Access a manifest and content

There are two styles for accessing an asset’s manifest. You can retrieve the whole manifest XML file together with the asset content through the HTTP interface, or you can use the methods defined by the Web service interface in an object-oriented manner.

Access using HTTP API

The HTTP API provides more low-level information and full control on the manifest, but you must be familiar with the RAS to correctly understand and modify the manifest. One advantage of this style is that you can access both the asset content and the asset manifest. This is useful because both are needed to create or modify an asset.

To access the asset in this style, you must first send an HTTP GET request using the asset ID and asset version as parameters. The response returned is a ZIP stream containing both the asset manifest and asset content. You can save this to a local disk or use standard ZIP tools to handle it. A sample of an asset’s ZIP file structure is shown in Figure 4.

An asset ZIP file contains the asset manifest file (manifest.rmd) and the artifacts. The manifest file describes the classification of the solution, its usage, and its related assets. Figure 5 shows a sample manifest file.

You can use standard ZIP and XML processing techniques to manipulate the asset content and its manifest according to the RAS. This gives you full control of the asset, but is less intuitive and more risky. For example, to add a classification term to the asset, you must add a nodeDescriptor element under the corresponding descriptorGroup element. However, if the descriptorGroup does not exist, you must add both the descriptorGroup and the nodeDescriptor elements. (See Access system metadata for how to retrieve the information needed by adding a new descriptorGroup element.) To add an artifact to the asset, you must first add the artifact in the correct position in the ZIP file, and then add an artifact entry element to the corresponding solution section of the asset manifest. All the modifications on the core asset file must follow the RAS.

After an asset is created or modified, you use an HTTPS POST request to commit the new asset to the Asset Manager repository. The HTTP POST parameters are explained in the Asset Manager InfoCenter (see Resources).

Listing 1 demonstrates how to use the HTTP interface to access an asset.

                        

String http_location =
"https://9.125.62.227:9080/com.ibm.ram.repository.web.ws.was/RAMSecure/
RAMAssetAccess.jsp?assetID={C986918C-8E01-4039-6D94-D56E0B6E57A6}&version=0.9";

		try {
			// use the https get to get the asset content
			InputStream is = HTTPHelper.getHTTPSContent(oneAssetHTTPLocation,
					username, password);

			ZipInputStream zis = new ZipInputStream(is);

			ZipEntry zipEntry;
			int len = 0;
			String name = null;
			byte[] buffer = new byte[512];

			while ((zipEntry = zis.getNextEntry()) != null) {
				ByteArrayOutputStream out = new ByteArrayOutputStream();
				name = zipEntry.getName();
				while ((len = zis.read(buffer, 0, buffer.length)) != -1) {
					out.write(buffer, 0, len);
				}
				out.flush();
				entryMap.put(name, out.toByteArray());
				out.close();
			}
		} catch (IOException e) {
			// TODO Auto-generated catch block
			e.printStackTrace();
		}
	byte[] mainfest = entryMap.get("manifest.rmd");     

Access using Web service API

The Web service interface is friendly to asset consumers. It provides objects and methods for accessing the asset manifest in an object-oriented style and offers full control on the extended metadata of the assets.

Once you are connected to the Web service interface, you can perform a search on assets in the Asset Manager repository, and then use the asset ID and version to get the metadata object of an asset. The metadata object contains the necessary information about the asset manifest. You can call the getManifest method to get the manifest file in the same way that you used the manifest.rmd file in the previous section, or you can invoke methods on the asset metadata objects to get the corresponding sections of the asset manifest. For example, you can invoke the getRelationships method to get the relatedAsset section in the asset manifest, invoke getArtifactsRoot to get the root of the artifact hierarchy and then invoke the getChildren method recursively to get the entire artifact hierarchy.

Some extended metadata, such as user tags and change history, can also be retrieved and modified by the Web service API. For more information on the Asset Manager Web service API, please refer to Resources.

Listing 2 demonstrates how to use the Web service API.

                                  
            
     try {
            //Get the asset metadata object
               AssetSO asset = ramWebService.getAsset(assetID, assetVersion, true,
	    true, true, true, true, true, true, true, true, "zh_CN");
			
	//Get the category schema list related to this asset object
	    CategorySchema[] categoryschemas=asset.getCategorySchemas();
			
	    for(int i=0;i<categoryschemas.length;i++){
	        CategorySchema oneCategorySchema=categoryschemas[i];
				
		//OO Style Access: get the categories related to this asset
		Category[] categories=oneCategorySchema.getCategories();
				
		// Recursively retrieve the sub categories
	                for(int j=0;i<categories.length;j++){
		    Category oneSubCategory=categories[j];
		    SubCategory[] subCategories=oneSubCategory.getSubCategories();
			//	......
		}
	}
   
  

Access system metadata

Some common system metadata (such as asset types, category schemas, and relationship types) are shared among the assets in the Asset Manager repository. This metadata is needed when manipulating the asset manifest. For example, you may need to retrieve the system classification hierarchy to get a better understand of the classification section of the manifest file, or you may need to know all the classification terms when you want to add a new classification to an asset. This section discusses how to access two types of system metadata: the category schema and the relationships.

Access category schemas

The Asset Manager classification system contains a set of category schemas. Each category schema contains a set of related terms. Each term has a unique identifier in the category schema, and this identifier is needed to understand the classification section in the asset manifest file.

First, you need to know how many category schemas are in the system. To get the list of all the category schema objects, use the getCategorySchemas method as shown here:

CategorySchemaSO[] categories = ramWebService.getCategorySchemas(null, true);

There are also two ways of accessing a category schema. One is to get a full XML description of the whole category schema, and the other is a recursive style using the methods defined in the Asset Manager Web service API. To retrieve the full XML content of a category schema, first get the URL of the category schema and then perform an HTTP GET on the schema’s URI. A sample of a category schema is shown in Figure 6.

The category schema contains a hierarchy of classification entries. Each entry is a specific element with two attributes: @xmi:id and @name. The @xmi:id is unique and it identifies which classification entry in the category schema is used to classify the asset in an asset manifest.

The other way to retrieve the category schema is to traverse the category schema objects by calling the getSubCategories method recursively. This style is more intuitive to users when they explore the category hierarchy from the top.

Access relationship types

The relationships between assets also play an important role in organizing the assets. You can retrieve the existing relationships of an asset through the asset manifest. However, when you want to add a new relationship to an asset, or add and delete a new relationship type when creating an asset, you need to list all the available relationship types in the Asset Manager server. These tasks can also be accomplished with the Web service API. Listing 3 demonstrates how to list all the relationship types in the Asset Manager repository.

                                              
      RelationshipType[] types = ramWebService.getAllAssetRelationTypes();
			
	for(int i=0;i<types.length;i++){
	    RelationshipType oneType=types[i];
	    String displayName=oneType.getDisplayName();
	    String reverseRealtionShipName= oneType.getReverseName();
	    String name= oneType.getName();
	}
       

Use caution when deleting a relationship type: deleting an existing relationship may cause the loss of the relatedAsset section of the asset manifest.

Interact with the asset life cycle

Asset Manager has a default asset life cycle definition. Once an asset is submitted, it can be reviewed and approved for public use, and an old version of the asset may be retired and archived when it is no longer applicable. The default asset life cycle is shown in Figure 7.

Asset Manager does not allow the customization of the asset life cycle. However, in a real development environment users may have their own life cycle definition and review processes for assets. This life cycle may not be completely aligned with Asset Manager’s default asset life cycle. To fill this gap, an externally-driven life cycle mechanism can be applied. You can first define your own life cycle and state transition rules, and then map the states of the customized life cycle to the default asset life cycle in Asset Manager. Finally, you can use an external trigger to transit the states of an asset in Asset Manager when the asset’s external state reaches a pre-defined transition point.

Listing 4 demonstrates how to manage an asset life cycle with an external trigger.

                                              
            
    // Get the asset metadata object
	AssetSO asset = ramWebService.getAsset(assetID, assetVersion, true,
		true, true, true, true, true, true, true, true, "zh_CN");

		String currentState = asset.getState().getName();
		String newState = "Approved";

		if (someConditionSatisfied == true) {
		    String[] message = ramWebService.changeAssetState(assetID,
		        assetVersion, newState, true);

			if (message == null) {
			              System.out.println("State Change Success");
				} else {
				System.out.println("State Change Failed");
				}
			}

     

Summary

Asset-based development is the best choice for developing a Service-Oriented Architecture (SOA) solution. This article proposes a solution that can easily enable heterogeneous applications to participate in the ABD process by integrating with Asset Manager. ABD promotes and accelerates the reuse of the modules and components both in the business and IT domain.

Back to top

Download

Information about download methods

Resources

• Rational Asset Manager 7.1 InfoCenter: For details on using the remote Web services API.
  
  
• Strategic Reuse with Asset-Based Development, Lee Ackerman et.al.: An IBM Redbook on asset-based development.
  
  
• Asset lifecycle management for service-oriented architectures, Grant Larsen and Jack Wilber (developerWorks, 2005).
  
  

About the authors

Tian Tan joined the SOA Design Center of the China Development Lab as a software engineer in 2007. In the past two years, he worked on the FMDM incubation project, focusing on Rational Asset Manager integration, metadata management, ontology, and the semantic web. He has extensive experience in Java, J2EE, Eclipse RCP and Web 2.0 related techniques. Tan Tian is an IBM Certified SOA Solution Designer.

Chuan Feng Li is a Software Engineer working at the SOA Design Center in the China Software Development Lab. He has more than 8 years of work experience in software development, including telecommunication applications, network management software, and SOA testing tools. He is currently technical leader of the SOA Federated Metadata Management (FMDM) incubation project, which is a key domain in next generation of SOA - Federated SOA.

Bei Bei Wang is a Software Engineer at the SOA Design Center in the China Development Lab. She focuses on SOA governance related topics, and is currently a developer working on the SOA Federated Metadata Management (FMDM) incubation project.

Xiao Xing Liang is a software engineer working at the SOA Design Center in the China Development Lab. He is an IBM Certified WebSphere Enterprise Developer and an IBM Certified SOA Solution Designer. His current focus is on SOA governance -elated topics including WebSphere Service Registry and Repository, Rational Asset Manager, Tivoli Application Dependency Discovery Manager, and Tivoli Change and Configuration Management Database.

Zhe Yan is a staff software engineer working at the SOA Design Center in the China Development Lab. He concentrates on SOA governance -elated topics, especially metadata federation. He is currently doing design and development related to the integration of WBG and WebSphere Services Registry and Repository.

Dr. Yu Chen Zhou is the SOA Governance Architect in the SOA Design Center, leading the the SOA Policy Toolkit, Federated Metadata Management, and WebSphere Services Registry and Repository development teams in China, and other governance-related efforts. He is an IEEE senior member and IBM Master Inventor.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Assets, ABD and Asset Manager
• Solution background
• Asset Manager content model
• Connect to the Web service and HTTP APIs
• Access a manifest and content
• Access system metadata
• Interact with the asset life cycle
• Summary
• Download
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Rational Asset Manager
• Demo: Automating the delivery of reliable software
• Webcast: Reduce cost and speed time to market with Quality Management and Asset Management
• Briefing: Jazz and Rational Team Concert
• Buy: Rational Asset Manager

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers