## SAS Java Metadata Interface used for use in remote and mid tier java applications.

## Overview

- Example 1: Server Connection
- Example 2: Get Repositories
- Example 3: Get Metadata Types
- Example 4: Create Objects
- Example 5: Read Objects
- Example 6: Delete Objects
- Example 7: Get all objects of a particular type
- Example 8: Get an existing object
- Sample Program

Provides a java object interface to the metadata server for SAS/Open Metadata Architecture. This provides a way to access a SAS Metadata Repository through the use of client java objects to represent server metadata. This is represented through the use of object interfaces, a factory to create objects, and methods for communicating with the metadata server.

The com.sas.metadata.remote package represents the remote implementation of the SAS Java Metadata Interface and can be used for multi-user and single-user applications.

The SAS Java Metadata Interface classes contained in the com.sas.metadata.remote package are used as a wrapper for the OMI (Open Metadata Interface) classes. The SAS Java Metadata Interface classes instantiate java objects to represent the OMA model. These objects use several support classes to create, cache, read, and write objects back and forth from the OMR. Support classes include the following:

1. MdFactory: The factory used for creating and deleting objects.
2. MdObjectStore: This is the caching mechanism used for making modifications to existing objects. All model objects, either new or existing, are created within an object store. Any modified objects that exist in an object store can be persisted to the server.
3. CMetadata: Base interface for all objects in the OMA model.
4. AssociationList: A List object used to contain association information between two objects in the model (for example, a table and its columns).
5. MdOMIUtil: Helper interface used for reading and writing metadata to and from the server.
6. MdOMRConnection: Used to make connections to OMR.

These classes can be used to make connections, create objects, search for objects, and write to the server.

## How to begin using the classes

The following steps outline what is required to setup and use the metadata classes from any environment. Two of the steps are required by all clients: an object factory must be instantiated and a connection to the metadata server must be established.

1. First, instantiate an instance of the MdFactory class.

       MdFactory factory = new MdFactoryImpl();

   If the application does not need to run within a remote environment, meaning only a single JVM is required, consider using the following to construct an instance of the factory. If the objects do not need to be remote, there is a considerable performance gain by using the following:

       MdFactory factory = new MdFactoryImpl(false);

2. Second, establish a connection to the metadata server. Each factory instance should have its own connection to the metadata server. The connections can be made via the MdOMRConnection interface. To retrieve a reference to this object:

       MdOMRConnection connection = factory.getConnection();

   Once the reference has been obtained, the connection to the server can be made:

       connection.makeOMRConnection(String host, String port, String userName, String password);

3. Now that a connection has been made, the factory is ready to be used. The object factory, MdFactory, can be used to create objects on the client. In order to create an object, a parent object store must be specified. The object store serves as the "Work Unit" or local cache of objects.

   To create a new object store:

       MdObjectStore store = factory.createObjectStore();

   To create existing objects on the client (objects that already exist in the OMR server):

       factory.createComplexMetadataObject(MdObjectStore parentStore, String objectName, String metadataType, String idOfExistingObject)

   To create new objects on the client (Objects that are created on the client and need to be persisted to the OMR server):

       factory.createComplexMetadataObject(MdObjectStore parentStore, String objectName, String metadataType, String shortRepositoryID)

4. When all changes have been made to the objects, the modifications can be persisted to the metadata server.

       store.updatedMetadataAll();

   This will seralize the object, and any of its changes, via XML to the metadata server. This method will ensure that all changes existing with an ObjectStore will be persisted together to the server. This includes all simple attributes as well as object associations. NOTE: When you create a new object on the client and write it to the server, a permament id will be assigned for the object by the server. This change will then be reflected across all object stores open on the client.

5. When an object store is no longer needed on the client (typically after you have performed an update), it is recommended to clean up the objects. This is to ensure that the memory footprint of the object store caches does not grow too large. Note, the objects may no longer be used after the store has been disposed of.

       store.dispose();

## MdFactory

The factory object is used for the following actions: creating object stores, creating new metadata objects, as well as deleting existing objects from the server. All metadata objects will have their metadata type, name, and object identifier set once created. Depending on the type of object, additional attributes and associations may be set. All objects must be created within an object store.

The MdFactory interface also contains an eventing mechanism that allows the client to be notified when certain changes have been made on the server. This includes new objects being created, existing objects being modified, as well as objects being deleted. By implementing the MdFactoryListener interface, the client can listen for when these types of events occur. To add these listeners, use the addMdFactoryListener() method.

## MdObjectStore

The object store is the central "Work Unit" for use on the client. The store contains a cache of every object created in the store as well as a list of all modified objects. This list of change objects is referred to as the change list. The change list is the store's mechanism for generating the proper UpdateMetadata requests to send to the server. The object store is removed from memory by calling the dispose() method on the store.

## CMetadata

The CMetadata interface is the root object used by the metadata model objects. All OMA objects inherit from this interface. This defines all the utility methods for the objects to read from and write to the server. These objects also contain the simple attributes: Name, FQID (object identifier), Description, as well as Created and Updated date/time values. All model objects inherit these attributes from the CMetadata object.

CMetadata objects persist themselves through the updateMetadataAll() method. This method writes the object if it is new or has any attribute/association changes, and all other modified objects contained within the same object store. This call does not persist to the server if the object store that owns this object is a child store, meaning the store was created from a parent store. In this case, the objects are just flushed up to the next higher store in the inheritance tree.

## AssociationList

An association list is a list that defines one side of an association between two objects. For example, in a Columns-Table association, one AssociationList object is created for the Column to DataTable side, while a separate AssociationList object is created for the opposite DataTable to Columns side. AssociationList objects are implemented as a Vector in Java so they contain the standard List methods.

Note: when establishing an association between two objects, both objects must exist within the same object store. If the objects are contained within different stores, incomplete metadata could be created when persisted to the server.

## MdOMIUtil

The MdOMIUtil interface is used as a wrapper around the IOMI java classes. All of the flags and options are the same as those defined in the IOMI documentation. This interface contains methods for retrieving the list of repositories on the server, a list of the available metadata types, and various searching routines.

To search for objects on the metadata server, the getMetadataObjectsSubset() method can be used. This method allows for the use of XMLSelect statements along with templates to search for and retrieve objects.

Once you have an object on the client, populating it with even more data (attributes and associations) can be done by using the getMetadataAllDepths() method. This also allows for a specification of a template for the return list of objects.

## MdOMRConnection

The MdOMRConnection interface is used to contain the connection to the SAS Metadata Server. Methods to connect as well as disconnect from the server are supported. Other methods are also available to establish connections to other IOM servers.