## Note:

Extension of the classes in this package is prohibited unless otherwise documented. Similarly, extension or implementation of the interfaces in this package is prohibited except as documented.

# Package com.sas.metadata.remote

@CodeSet("sas.platform") @SASScope("ALL") package com.sas.metadata.remote

## Provides a java object interface to the metadata server using the SAS/Open Metadata Architecture.

## 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 using the 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 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. It is intended that each user has their own factory instance.

       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.

- Related Packages
  Package
  Description
  com.sas.metadata.remote.entities
  Provides a way of serializing com.sas.entities information to SAS Metadata Server in Java applications.
- Class
  Description
  AbstractExtension
  The SAS Metadata Model supports extensions to enable end users and application developers to define additional attributes that are not part of an object's metadata type definition.
  AbstractJob
  A job is a set of processes that initiate a process or create an output such as a data store or output table.
  AbstractPrompt
  The parent class for types used by the SAS Prompt Interface.
  AbstractProperty
  Used to contain name/value pairs.
  AbstractTransformation
  The parent type for transformation types.
  AccessControl
  An access control is an object that relates an identity and a permission to a resource in order to regulate access to the resource.
  AccessControlEntry
  The AccessControlEntry metadata type is used to define an access control directly on a resource.
  AccessControlTemplate
  The AccessControlTemplate (ACT) metadata type enables you to define a template of individual users, groups, and permissions that can be applied to multiple resources.
  Action
  An action that will be performed when a stated condition is met.
  Aggregation
  A summary of detail data that is stored with or referred to by a cube.
  AnalyticColumn
  Contains analytic attributes to apply to a column.
  AnalyticContext
  References a location that has SAS analytic content.
  AnalyticTable
  Contains analytic attributes to apply to a table.
  ApplicationAction
  Represents a feature/action of an application.
  ArchiveEntry
  One of several metadata types used to describe the physical location of some form of content.
  ArchiveFile
  Represents an archive, such as a tar file or a zip file, which may contain entries.
  AssociationList
  Extension of List to manage associations between objects.
  AssociationProperty
  The SAS Metadata Model provides a Prototype metadata type to define templates that can be used to create metadata entities.
  AttributeProperty
  The SAS Metadata Model provides a Prototype metadata type to define templates that can be used to create metadata entities.
  AuthenticationDomain
  Authentication domains provide logical groupings for resources and logins in a metadata repository.
  CalculatedMeasure
  In a dimension, a member whose value is derived from the values of other members.
  CalculatedMember
  Beginning in SAS 9.3, represents a new member in a dimension of a cube.
  Change
  This type is used by Change Mangement.
  Classifier
  A classifier is an element that describes structural and behavioral features.
  ClassifierMap
  Used to map any number of Classifier objects to any number of Classifier objects.
  CMetadata
  Column
  Represents a column in a table, view, etc.
  ColumnHierarchy
  Used to assign columns to a hierarchy for the associated data table.
  ColumnRange
  Represents a range of columns.
  COMConnection
  Represents a COM connection.
  Condition
  A condition that when met may activate an action or set of actions.
  ConditionActionSet
  A set that contains the condition that must be met and the set of actions to be performed.
  ConditionalPrecedence
  The preceding and succeeding steps based on the stated condition.
  ConfiguredComponent
  Installed software that has configuration information in addition to the licensing information.
  Connection
  Represents the information required to connect to a server.
  ContentLocation
  The supertype for all types that provide location information.
  ContentType
  Describes the type of content contained in the associated object.
  Cube
  A logical set of data that is organized and structured in a hierarchical, multidimensional arrangement.
  CustomAssociation
  Defines a custom association between any two metadata objects.
  DatabaseCatalog
  A namespace for contained database schemas.
  DatabaseSchema
  A relational schema that contains tables that are not in SAS data sets.
  DataSourceName
  Represents a data source name (DSN) that is a construct used by the SAS table server to identify a data source definition.
  DataTable
  An abstract type that represents an object that contains a set of columns.
  DeployedComponent
  An abstract metadata type that represents installed software.
  DeployedDataPackage
  A container of data files (files that contain data) or other Deployed Data Packages.
  Device
  Describes location information for SAS Filerefs.
  DeviceType
  Defines a prototype for a specific supported device.
  Dimension
  A group of closely related hierarchies.
  Directory
  Represents a physical operating system path.
  Document
  A Document is a web page or other conent that contains documentation pertinent to the object to which this document is related.
  Email
  An e-mail address.
  Event
  Describes a condition that occurs that drives other actions, ie. jobs, to be processed.
  Extension
  Extension enables end users and application developers to define additional attributes that are not part of an object's metadata type definition.
  ExternalIdentity
  This is an ID associated with the object in some other context, such as a GUID or DN for LDAP .
  ExternalTable
  Represents a table in an external data file.
  FastMetadata
  FastMetadata is a lightweight wrapper for the attribute and association maps returned by the getMetadataNoCache and getMetadataObjectsNoCache methods of `MdOMIUtil`.
  FavoritesContainer
  Contains one or more links to an object that a user has marked as a favorite.
  Feature
  A feature is a property that is encapsulated within a Classifier.
  FeatureMap
  Used to map any number of Feature objects to any number of Feature objects.
  File
  Represents a file in the file system.
  FitStatistic
  Usually a measure of the accuracy of a predicted value.
  ForeignKey
  Represents the fact that a table contains a foreign key to another table.
  GlobalFormula
  PROC OLAP and OLAP CUBE Studio enable users to define formulas for the dimensions of a cube that result in the creation of calculated members and named sets.
  Group
  This type represents the ability to group metadata together.
  GroupByClause
  DEPRECATED: Has an association to the columns used to group this data.
  HavingClause
  DEPRECATED: Represents a Having clause in an SQL statement.
  Hierarchy
  An arrangement of members of a dimension into levels that are based on parent-child relationships.
  HierarchyLevel
  Represents a level within one and only one hierarchy.
  Identity
  Identity - abstract class for objects that identify an entity.
  IdentityGroup
  Grouping mechanism for identity objects.
  Index
  Represents an index on a physical structure.
  InternalLogin
  Internal use only.
  ITChannel
  A content distribution center.
  ITContentSubscriber
  A subscriber profile for content subscribers.
  ITEventSubscriber
  A subscriber profile for event subscribers.
  ITFilter
  A filter string is used to include or exclude content going to a specific subscriber.
  ITSubscriber
  A subscriber profile is used to control how published content is delivered to a user.
  JFJob
  Represents a job that has been or will be scheduled in the LSF JobFlow.
  Job
  Groups transformation activities to be an actual runtime unit.
  Join
  The output of a Join is limited to one JoinTable.
  JoinTable
  DEPRECATED: Represents an instance of a join between two tables.
  Key
  Represents keys on tables.
  KeyAssociation
  Represents the relationship between two columns in a foreign key, unique key relationship.
  Keyword
  The name attribute of this object is a single word that can be used to identify this object.
  Level
  An element of a dimension hierarchy.
  LocalizedResource
  Contains the localized values for a particular locale as defined by the LocalId attribute.
  LocalizedType
  This is the abstract supertype for all of the types that have localized resources.
  Location
  This type represents a location that includes a type (is it a street address, or an office number), as well as address information (street, city, country).
  LogicalColumn
  The supertype for Column, which is part of a relational table, and Measure, which is used with OLAP types.
  LogicalServer
  Used to define a homogeneous group of servers.
  Login
  Represents login information for a given user in a given authentication domain.
  Machine
  Represents a physical machine.
  MdConnectionEvent
  The event class used for signalling clients when a connection to the metadata server has been lost.
  MdConnectionListener
  Interface used for notifying clients when a connection to the metadata server has been lost.
  MdEvent
  MdEvent is used to notify interested parties that state has changed in the event source.
  MdException
  This exception type is used to define a metadata exception in general, whether it be a read/write/parse exception itself.
  MdFactory
  The MdFactory interface is used for controlling the creation of metadata objects and object stores.
  MdFactoryEvent
  This is the event class used for signalling when objects are created, modified, and deleted on the server.
  MdFactoryImpl
  This creates objects and Object Stores to be used by views of the metadata.
  MdFactoryListener
  Interface used for notifying clients when changes have been persisted to the server.
  MdObjectBase
  Root class of all metadata classes.
  MdObjectBaseUtil
  Provides the Store object and event interactions for Metadata objects.
  MdObjectBaseXML
  Provides the XML object interactions for Metadata objects.
  MdObjectFactoryListener
  This Listener handles events for objects creation and deletion on the server.
  MdObjectListener
  Details events that are generated for an individual object.
  MdObjectStore
  This a store of objects for a view's interaction.
  MdOMIUtil
  Used to perform operations against the metadata server, such as querying and deleting objects.
  MdOMRConnection
  Used to manage connections the the SAS/Open Metadata Repository.
  MdRepositoryUtil
  The interface defining the utility class for retrieving repository information.
  MdSecurityUtil
  Utility class used for retrieving the necessary security permissions for a metadata object.
  MdServerStore
  This is the Main store of objects (Cache) for interactions with the server.
  MdStore
  This describes the base store object for metadata
  MdStoreIDChangeListener
  The listener interface for an object store hashmap and its contained items.
  MdStoreListener
  The listener interface for an object store hashmap and its contained items.
  Measure
  A special dimension that contains summarized numeric data values that are analyzed.
  Memory
  Represents a result of a transformation that resides in memory on the server.
  MetadataObjects
  This interface defines the objects of the SAS Open Metadata Architecture model as constant variables.
  MetadataResource
  Each package has a standard set of resources named PropertyBundle.
  MetadataState
  This class defines the state that the attributes and association lists of an object can be.
  MiningResult
  Represents a SAS Enterprise Data Mining Model that is a formula or algorithm that computes outputs from inputs.
  NamedService
  Describes the name of the service and how the name is used (as rebind, bind, or lookup).
  NamedSet
  Beginning in SAS 9.3, represents a named set in dimension of a cube.
  NumericExtension
  This allows an application to create a numeric extension to any object.
  OLAPProperty
  An attribute associated with members of a given dimension level.
  OLAPSchema
  This is a grouping of Cubes accessible from a SAS OLAP server.
  OnClause
  DEPRECATED: Represents an SQL ON clause.
  OpenClientConnection
  An abstract type that represents the connection information needed by an open client to access a deployed component.
  OrderByClause
  Has an association to columns used to order the data.
  Permission
  A permission represents an action that a user may attempt against a resource in the metadata server.
  PermissionCondition
  Stores an expression that is applied to conditionally grant a user or group access to a resource.
  Person
  This type represents the information kept about a person.
  Phone
  A phone number and the type of phone number (home, office, mobile, fax).
  PhysicalTable
  A "materialized" table that resides in a database or a file system.
  PrimaryType
  The PrimaryType subtypes are the starting point for modeling a logical metadata definition.
  Prompt
  For use by the SAS Prompt Interface.
  PromptGroup
  For use by the SAS Prompt Interface.
  Property
  A parameter, option or other type of information that is used to tailor a metadata object.
  PropertyGroup
  Represents a group of properties.
  PropertySet
  A PropertySet contains a complete set of properties to be used by the OwningObject in a particular context.
  PropertyType
  Defines the data type of a property.
  Prototype
  Used to create a template for creating other metadata objects or set of metadata objects that represent a concept.
  PrototypeProperty
  This is the super type for types that define properties that are for prototype objects only.
  PSColumnLayoutComponent
  Provides the information needed to lay a PortalPage out in columns.
  PSLayoutComponent
  A UI element that designates how Portlets should be laid out on a PortalPage.
  PSPortalPage
  A PortalPage gathers and displays information in the Portal, and can be customized.
  PSPortalProfile
  A SAS Information Delivery Portal user's portal information, which defines the basic functionality of the portal.
  PSPortlet
  A Web component that is managed by a Web application and that is aggregated with other portlets to form a page within the application.
  QueryClause
  This abstract type represents types that are used to define the transformations that are performed.
  QueryTable
  Result set of a query.
  RelationalSchema
  The abstract type that acts as the supertype for any type that can contain table objects.
  RelationalTable
  Represents a relational table, one that does not have a physical representation.
  Report
  Represents the result of data being transformed into a report.
  ResponsibleParty
  This metadata type associates a responsibility with an identity.
  Role
  This object describes a role of of an object, and the context of the role.
  Root
  This is an abstract type that is the supertype for all of the other metadata types.
  RowSelector
  Used to document a SAS DATA step SELECT statement.
  SASCatalog
  Represents a SAS file that stores many different kinds of information in smaller units called catalog entries.
  SASCatalogEntry
  Represents a separate storage unit within a SAS catalog.
  SASClientConnection
  Represents the information needed by SAS software to connect to other servers.
  SASFileRef
  Represents a name temporarily assigned to an external file or to an aggregate storage location that identifies it to SAS.
  SASLibrary
  Represents a SAS library.
  SASLicense
  Used to document the setinit information for SAS products.
  SASPassword
  Represents the storage of SAS passwords for SAS tables or connections.
  Search
  This object is used to store information for search definitions.
  SecondaryType
  The SecondaryType subtypes are used along with the PrimaryType subtypes to create a logical metadata definition for an object.
  SecuredLibrary
  A SecuredLibrary object is created for a SAS physical library when it is bound to metadata with the AUTHLIB procedure of SAS.
  SecuredTable
  A SecuredTable object is created for a physical SAS data set when a data set with the same name is first created in a metadata-bound library.
  SecurityRule
  This is an abstract class from which other "SecurityRules" will derive.
  SecurityRuleScheme
  This class is used to group SecurityRules into a unit.
  SecurityTypeContainmentRule
  A SecurityTypeContainmentRule tells the authorization facility how to find parent objects for a particular metadata type.
  Select
  Used to document an SQL select statement.
  ServerComponent
  Represents servers and spawners.
  ServerContext
  Used to define an application context for non-homogeneous group servers.
  ServiceComponent
  Represents software that acts as a service.
  ServiceType
  The types of services available from a DeployedComponent.
  SharedDimension
  Shared dimension is contained by its schema and may be used by more than one cube.
  SoftwareComponent
  Used to define an application hierarchy.
  StepPrecedence
  The preceding and succeeding steps in a process.
  Stream
  Represents a stream of data.
  SXLEMap
  Root node for SXLE map definition.
  SyncStep
  The SyncStep is used to define a part of workflow.
  TableCollection
  A classifier that defines a set of tables that all share the same characteristics but that should be treated as one classifer for display purposes.
  Target
  Represents a variable whose values are known in one or more data sets that are available (in training data, for example) but whose values are unknown in one or more future data sets (in a score data set, for example).
  TCPIPConnection
  Contains information for making a TCP/IP connection to a server.
  Text
  The superclass for files, SAS catalog entries and text stored in the repository itself.
  TextStore
  Represents storing text in the repository.
  Timestamp
  This object contains a timestamp and the role of the timestamp.
  Transformation
  This type is used for generic transformations such as stored procedures.
  TransformationActivity
  TransformationActivity contains TransformationSteps.
  TransformationStep
  TransformationStep contains mapping objects.
  Tree
  This type represents a tree that is the root node for a hierarchy of groups of metadata.
  TSNameObject
  Table server name object.
  TSNamespace
  Table server namespace.
  TypeDefinition
  Type definition is used to describe members of the SAS type dictionary.
  UniqueKey
  A representation of the unique and primary keys of a table.
  UnitofTime
  Unit of time.
  UnsupportedPlatformVersionException
  Variable
  Used to define substitution strings and the replacement values.
  WhereClause
  DEPRECATED: Represents a Where SQL Clause.
  WorkTable
  Represents a table that is created as part of running SAS code that is not intended to be persisted.
  XMLUtil
  Contains utility methods for xml processing.
  XPath
  Used to describe an XPath location path.