Get Metadata in Oracle Database Using IMetadataRetrievalContract

Статья
02/02/2021

The Microsoft BizTalk Adapter for Oracle Database exposes an IMetadataRetrievalContractendpoint that you can use to browse and search for Oracle database artifacts and to retrieve metadata for operations in the form of a Web Services Description Language (WSDL) document.

The IMetadataRetrievalContract interface is implemented by the Microsoft Windows Communication Foundation (WCF) Line of Business (LOB) Adapter SDK and provides metadata browse, search, and retrieval capabilities. In addition to the IMetadataRetrievalContract interface, the WCF LOB Adapter SDK exposes the MetadataRetrievalClient class, which implements the interface. You can use either an IMetadataRetrievalContract channel or a MetadataRetrievalClient to work with metadata; the methods exposed to browse, search, and retrieve metadata are the same in each case.

The following sections provide information about how to use the IMetadataRetrievalContract interface.

The IMetadataRetrievalContract Interface

The following table provides information about important classes that are used when you work with the IMetadataRetrievalContract interface.

Class or Interface	Description
IMetadataRetrievalContract interface (Microsoft.ServiceModel.Channels)	Defines the Browse, Search, and GetMetadata methods. You invoke these methods either by using an IMetadataRetrievalContract channel or a MetadataRetrievalClient to work with adapter metadata.
MetadataRetrievalClient class (Microsoft.ServiceModel.Channels)	Implements the IMetadataRetrievalContract interface. You can create an instance of this class and configure it for your Oracle database by providing an OracleDBBinding and an EndpointAddress. Then you can invoke its methods to work with metadata.
MetadataRetrievalNode class (Microsoft.ServiceModel.Channels)	Represents a metadata node on the adapter. The Browse and Search methods return nodes of this type, and the GetMetadata method takes nodes of this type as a parameter.
ServiceDescription class (System.Web.Services.Description)	Provides a means of creating and formatting a valid WSDL document file. The GetMetadata method returns a ServiceDescription object.

Metadata Node IDs

The adapter organizes its metadata as a hierarchical tree of nodes. Within this tree structure there are two types of metadata nodes:

Operation nodes represent operations that the adapter surfaces on Oracle database artifacts. Operation nodes are the leaves of the tree.
Category nodes represent Oracle database artifacts and groupings of Oracle database artifacts that do not directly correspond to an operation on the adapter. Category nodes are the branches of the tree; they contain other category nodes and/or operation nodes. For example, Oracle tables and packages are represented as category nodes.

Each metadata node surfaced by the adapter is identified by a unique node ID. For more information about the metadata node IDs surfaced by the adapter, see Metadata Node IDs. You use these node IDs to specify target Oracle database artifacts when you use the IMetadataRetrievalContract interface to browse, search, and retrieve metadata.

Binding Properties

Whether you use an IMetadataRetrievalContract channel or an IMetadataRetrievalClient to work with metadata, you must specify an OracleDBBinding when you create the instance.

There are several binding properties that affect how the adapter generates metadata. These properties are:

EnableSafeTyping
UseSchemaInNamespace
PollingStatement

Important

If you want to retrieve metadata for the POLLINGSTMT operation you must set the PollingStatement binding property.

You should ensure that these binding properties are set to the values required for your application before you open the metadata retrieval object. For more information about the Oracle Database adapter binding properties, see Read about the Oracle Database adapter binding properties.

Browsing Metadata Nodes

You use the Browse method to return all the metadata nodes that are contained in a parent node. The following example browses for the first three schemas on the Oracle database. In this example, client is an instance of MetadataRetrievalClient.

// The first parameter is the node ID.   
// The second parameter is the start index.  
// The third parameter is the maximum number of nodes to return.  
                MetadataRetrievalNode[] nodes = client.Browse(MetadataRetrievalNode.Root.NodeId, 0, 3);

Important

You can only browse category nodes; you cannot browse operation nodes.

Searching for Metadata Nodes

You use the Search method to perform a search for nodes contained by a parent node. The adapter supports wildcard characters in search expressions; for example you can specify the percent (%) wildcard character to match zero or more characters. The following example shows a search for all the tables in the SCOTT schema that contain the string "EMP". In this example, client is an instance of MetadataRetrievalClient.

// Search for all nodes that contain "EMP" under the SCOTT.Table node.  
// The parameters are the parent node ID, the search expression, and   
// the maximum number of nodes to return.  
IMetadataRetrievalNode[] nodes = client.Search("http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table", "%EMP%", 3);

Important

Searching is only supported on a limited set of nodes. For more information about the nodes on which search is supported and about the wildcard characters supported in search expressions, see Metadata Node IDs.

Retrieving Metadata (WSDL) for Operations

You use the GetMetadata method to retrieve a service description (WSDL document) for a group of operation nodes. The following example retrieves a service description that contains all of the operations that the adapter surfaces for the SCOTT.EMP table by specifying its node ID. In this example, client is an instance of MetadataRetrievalClient.

// Get a service description that contains all of the operations   
// surfaced for the SCOTT.EMP table. The IsOperation  
// property is set false because this is a category node.  
nodes = new MetadataRetrievalNode[1];  
nodes[0] = new MetadataRetrievalNode();  
nodes[0].NodeId = "http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table/EMP";  
nodes[0].IsOperation = false;  
System.Web.Services.Description.ServiceDescription description = client.GetMetadata(nodes);

Important

The IsOperation property should be false for category nodes and true for operation nodes.

Using a MetadataRetrievalClient

Creating and using a MetadataRetrievalClient is much the same as any other WCF client. You create the client by specifying an endpoint and an instance of OracleDBBinding. You can do this either declaratively in configuration or imperatively in your code. You then invoke the methods of the MetadataRetrievalClient to browse, search, and retrieve metadata from the adapter.

The following example shows how to use a MetadataRetrievalClient to browse, search, and retrieve metadata from the Oracle Database adapter. The example demonstrates:

Browsing the root node of the metadata tree for Oracle Database schemas.
Searching for the tables in the SCOTT schema with names that contain the string "EMP".
Retrieving metadata for all of the operations supported for the SCOTT.EMP table by passing a category node to the GetMetadata method.
Retrieving metadata for the POLLINGSTMT operation by passing the POLLINGSTMT operation node to the GetMetadata method..

using System;  
using System.Collections.Generic;  
using System.Text;  
  
using System.ServiceModel;  
using Microsoft.Adapters.OracleDB;  
using Microsoft.ServiceModel.Channels;  
  
using System.Web.Services.Description;  
  
namespace OracleMetadataRetrieval  
{  
    class NodeWriter  
    {  
        // This method writes the value of a collection of metadata retrieval nodes  
        // to the console  
        public void Write(string title, MetadataRetrievalNode[] nodes)  
        {  
            Console.WriteLine(title);  
            Console.WriteLine();  
  
            //write all the nodes returned to the console.  
            foreach (MetadataRetrievalNode node in nodes)  
            {  
                Console.WriteLine("NodeId = " + node.NodeId);  
                Console.WriteLine("\tDirection   = " + node.Direction.ToString());  
                Console.WriteLine("\tIsOperation = " + node.IsOperation.ToString());  
                Console.WriteLine("\tDisplayName = " + node.DisplayName);  
                Console.WriteLine("\tDescription = " + node.Description);  
            }  
            Console.WriteLine();  
        }  
    }  
  
    class Program  
    {  
        static void Main(string[] args)  
        {  
            MetadataRetrievalClient client = null;  
            NodeWriter nodeWriter = new NodeWriter();  
  
            try  
            {  
                // create a binding and   
                // set the PollingStatement binding property if you want to  
                // return metadata for the POLLINGSTMT operation  
                OracleDBBinding binding = new OracleDBBinding();  
                binding.PollingStatement = "SELECT * FROM EMP";  
  
                // Set PollingId parameter if you want to alter the namespace of the POLLINGSTMT operation  
                EndpointAddress address = new EndpointAddress("oracledb://ADAPTER?PollingId=1");  
  
                client = new MetadataRetrievalClient(binding, address);  
                client.ClientCredentials.UserName.UserName = "SCOTT";  
                client.ClientCredentials.UserName.Password = "TIGER";  
                client.Open();  
  
                // Browse for the first 3 (schema) nodes directly under the root  
                // The parameters are the parent Node ID, the start index, and the maximum number  
                // of nodes to return  
                MetadataRetrievalNode[] nodes = client.Browse(MetadataRetrievalNode.Root.NodeId, 0, 3);  
                nodeWriter.Write("Browse results for the root node:", nodes);  
  
                // Search for first 3 tables that contain "EMP" in the SCOTT schema  
                // The parameters are the parent node ID, the search expression, and the maximum number  
                // of nodes to return  
                nodes = client.Search("http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table", "%EMP%", 3);  
                nodeWriter.Write(String.Format("Search results for \"%EMP%\" under {0} node:", "http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table"), nodes);  
  
                // Get a WSDL document that specifies a contract that contains the operations  
                // surfaced for the SCOTT.EMP table. The IsOperation property is set false  
                // because this is a category node.  
                nodes = new MetadataRetrievalNode[1];  
                nodes[0] = new MetadataRetrievalNode();  
                nodes[0].NodeId = "http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table/EMP";  
                nodes[0].IsOperation = false;  
                System.Web.Services.Description.ServiceDescription description = client.GetMetadata(nodes);  
                description.Write("EmpTableContract.wsdl");  
  
                // Get a WSDL document that specifies a contract that contains the   
                // the POLLINGSTMT operation. The IsOperation property is set true  
                // because this is an operation node.  
                // Note that the operation NodeId is equivalent to the message action.  
                nodes = new MetadataRetrievalNode[1];  
                nodes[0] = new MetadataRetrievalNode();  
                nodes[0].NodeId = "http://Microsoft.LobServices.OracleDB/2007/03/POLLINGSTMT";  
                nodes[0].IsOperation = true;  
                description = client.GetMetadata(nodes);  
                description.Write("PollingContract.wsdl");  
  
            }  
            catch (Exception ex)  
            {  
                Console.WriteLine("Exception is: " + ex.Message);  
            }  
            finally  
            {  
                if (client != null)  
                {  
                    if (client.State == CommunicationState.Opened)  
                        client.Close();  
                    else  
                        client.Abort();  
                }  
            }  
        }  
    }  
}

The following shows the output of this program on the console. You can see the structure of the metadata retrieval nodes returned by each method. The program also writes two WSDL documents to files.

Browse results for the root node:  
  
NodeId = http://Microsoft.LobServices.OracleDB/2007/03/ADAPTERTEST  
        Direction   = Outbound  
        IsOperation = False  
        DisplayName = ADAPTERTEST  
        Description = Owned By ADAPTERTEST  
NodeId = http://Microsoft.LobServices.OracleDB/2007/03/ADAPTEST  
        Direction   = Outbound  
        IsOperation = False  
        DisplayName = ADAPTEST  
        Description = Owned By ADAPTEST  
NodeId = http://Microsoft.LobServices.OracleDB/2007/03/ADMIN123  
        Direction   = Outbound  
        IsOperation = False  
        DisplayName = ADMIN123  
        Description = Owned By ADMIN123  
  
Search results for "%EMP%" under http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table node:  
  
NodeId = http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table/AEMP  
        Direction   = Outbound  
        IsOperation = False  
        DisplayName = AEMP  
        Description = Table.AEMP  
NodeId = http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table/EMP  
        Direction   = Outbound  
        IsOperation = False  
        DisplayName = EMP  
        Description = Table.EMP  
NodeId = http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table/EMP1  
        Direction   = Outbound  
        IsOperation = False  
        DisplayName = EMP1  
        Description = Table.EMP1

Using an IMetadataRetrievalContract Channel

You can also create an IMetadataRetrievalContract channel and then use this channel to browse, search, and retrieve metadata from the adapter. (The method signatures are the same as for the MetadataRetrievalClient class.) The following example shows how to do this.

…  
//Create a binding and endpoint address.  
OracleDBBinding binding = new OracleDBBinding();  
EndpointAddress address = new EndpointAddress("oracledb://ADAPTER/");  
  
//Create and open a channel factory that will return an IMetadataRetrievalContract object, on which browse, search, and get can be performed.  
ChannelFactory<IMetadataRetrievalContract> factory = new ChannelFactory<IMetadataRetrievalContract>(binding, address);  
factory.Credentials.UserName.UserName = "SCOTT";  
factory.Credentials.UserName.Password = "TIGER";  
factory.Open();  
  
//Obtain an IMetadataRetrievalContract channel from the factory.  
IMetadataRetrievalContract channel = factory.CreateChannel();  
  
//Perform a search using the channel.  
MetadataRetrievalNode[] nodes = channel.Search("http://Microsoft.LobServices.OracleDB/2007/03/SCOTT/Table", "%EMP%", int.MaxValue);  
…

Поделиться через

Get Metadata in Oracle Database Using IMetadataRetrievalContract

The IMetadataRetrievalContract Interface

Metadata Node IDs

Binding Properties

Browsing Metadata Nodes

Searching for Metadata Nodes

Retrieving Metadata (WSDL) for Operations

Using a MetadataRetrievalClient

Using an IMetadataRetrievalContract Channel

See Also

Обратная связь

Дополнительные ресурсы