MethodInstance

A MethodInstance object describes how to use a method via a specific set of default values and a method instance type, which is a Business Data Catalog semantic. A MethodInstance object is a reference to a method, plus the default values for the parameters. A MethodInstance object can be executed, whereas a Method object cannot be executed. A single method can have multiple method instances, with each MethodInstance object being a combination of the method signature and a set of default values. You can use method instances to execute the same method with different default values.

Method instances are especially useful for complex Web services. If a method returns multiple or nested complex structures, the MethodInstance metadata can specify which of the structures or part of the structure to return to the client. To completely define a MethodInstance object, you can optionally define a TypeDescriptor element along with the return parameter in XML. Following is an example.

<MethodInstance Name="bla" Type="Finder" ReturnParameterName="foo" ReturnTypeDescriptorName="baz" ReturnTypeDescriptorLevel="5">

The attribute ReturnTypeDescriptorName is optional. If it is not specified, the Business Data Catalog assumes the root TypeDescriptor of the Return parameter element. The attribute ReturnTypeDescriptorLevel is also optional. If it is not specified and there are more than one similarly named type descriptors an exception is thrown. If there are more than one similarly named type descriptors at the same level (which is rare), the first is assumed. This flexibility is important because it allows reuse of a WebMethod object in multiple ways. Consider a WebMethod that returns collections of Customers, and each Customer contains a collection of Addresses. Three Business Data Catalog MethodInstance objects use this WebMethod: a Customer Finder, a Customer SpecificFinder and a CustomerToAddress Association (returns a Customer's Addresses). In the MethodInstance model, the metadata author must define just the portion of the Return parameter that is of relevance, by allowing a user to specify the TypeDescriptor within the Return parameter.

Associations are derived classes of MethodInstance classes and the Association definition format also optionally takes in ReturnTypeDescriptor values.

<Association Name="CustomerToAddresses" AssociationMethodEntityName="Customer" AssociationMethodName="GetCustomerByID" AssociationMethodReturnParameterName="Customer" AssociationMethodReturnTypeDescriptorName="CustomerAddresses" AssociationMethodReturnTypeDescriptorLevel="1">
      <SourceEntity Name="Customer" />
      <DestinationEntity Name="Address" />
    </Association>

Finally, the object model for MethodInstance also provides a ReturnTypeDescriptor accessor/property. The ReturnParameter is implicitly part of the ReturnTypeDescriptor, and because the object model works with object references, there is no further need to specify a ReturnParameter when using the object model.

Certain method instances have special purposes that enable generic clients.

Finders and SpecificFinders

A Finder is a special method that returns entity instances. A SpecificFinder returns exactly one entity instance. Finder methods are static methods and do not take a key as an input parameter. SpecificFinder methods are also static methods but they take a key (ID) explicitly.

Entities that can be reached only by association must have zero finders. Other entities should have one Finder method that returns multiple instances, and one SpecificFinder method that returns a single instance, given an ID.

For example, for the Customer entity, the Finder method might be SELECT * FROM Customers and the SpecificFinder method might be SELECT * FROM Customers WHERE CustomerID = id.

If you do not define Finder methods, your entity cannot be used in a Business Data List Web Part; if you do not define SpecificFinder methods, that entity cannot have actions on it, cannot be searched or indexed, and cannot be used in any of the Business Data features except the Related List Web Part.

To qualify for a Finder, the corresponding method must take filterable parameters as input and return collections of records, where each record must contain the key of the entity instance it represents. To qualify as a SpecificFinder, the corresponding method must take the entity instance key as one of the input parameters and must return fields, of which one of the fields is the key.

Following is a slightly more complex example of a Finder method that has filterable parameters.

SELECT ProductID, Name, ProductNumber, ListPrice FROM Product WHERE (ProductID >= @MinProductID) AND (ProductID <= @MaxProductID) AND (Name LIKE @Name) AND ProductNumber LIKE @ProductNumber)

Finder methods and SpecificFinder methods need not return the same fields. You might have scenarios where the SpecificFinder method returns more fields than the Finder method. However, they both must return the identifiers defined on the entities.

A Finder and a SpecificFinder method must have exactly one corresponding method instance.

A SpecificFinder method plays an important role in Enterprise Search and indexing. A Business Data Catalog crawl has two phases:

• ID enumeration: Fetch all entity instance IDs.

• Detail fetch: Fetch details for each entity instance.

An IDEnumerator, described later in this topic, returns the IDs and the SpecificFinder method returns the details for each entity instance.

ViewAccessors

A view is a collection of fields for an entity. The view of an entity contains the fields returned by one of its MethodInstance objects such as Finder and SpecificFinder. A ViewAccessor is another special method that returns a non-default view, that is, a different set of fields from the business application. ViewAccessor methods are instance methods that take a key (ID) implicitly; that is, you do not provide the key. The Business Data Catalog provides the key automatically.

Entities have zero or more ViewAccessor methods.

Although Finder and SpecificFinder methods can have only one method instance, ViewAccessor methods can have one or more method instances. This flexibility is useful when the same method returns multiple structures, each of which makes up a view. In systems such as SAP, there are APIs (for example, BAPI_CUSTOMER_GETDETAIL2) that return multiple collections of related fields to the user. The Customer GetDetails API, for example, might return a structure containing financial data, a structure containing address data, and so on.

IDEnumerator

A Business Data Catalog crawl has two phases:

• ID enumeration: Fetch all entity instance IDs.

• Detail fetch: Fetch details for each entity instance.

An IDEnumerator method returns the list of IDs (unique keys for each entity that should be searchable, and the SpecificFinder method returns the details for each entity instance. This enables indexing of the entities whose IDs the IDEnumerator method returns.

Entities have zero or one IDEnumerator method. IDEnumerator methods are not limited to returning a list of IDs. If they return other fields in the return parameter, the Business Data Catalog ignores them during the crawl.

The LastIdSeen filter enables chunking for IDEnumerator methods. For Web services and other nonstreaming back-end applications, use the LastIdSeen filter in your IDEnumerator method to improve performance, as follows.

SELECT TOP 100 Id FROM Customers WHERE Id>=@LastIdSeen
ORDER BY Id

AccessChecker

An AccessChecker is a method that returns the rights a user has on one or more entity instances. A right can be a single bit or a collection of bits. The rights, once determined, can be used by Business Data client applications via the Entity.CheckAccess method. For example, consider a user building a custom Web Part on the Business Data Catalog that displays Create, Edit, and Delete Actions for an EntityInstance. Now by defining an AccessChecker, the user could call Entity.CheckAccess and then conditionally enable one or more of the Actions depending on what rights are returned. For AccessChecker samples, see AccessChecker Samples.

Entities have zero or one AccessChecker method per Entity.

GenericInvoker

A GenericInvoker is a method that you can invoke in the back-end LOB application that is not one of the methods described previously. For example, you can use a GenericInvoker method to execute a method in the back-end application to edit an entity or to update the unit price in the Products table.

Entities have zero or more GenericInvoker methods.

GenericInvoker methods are extremely useful if you are writing a custom Web Part that must invoke logic in a back-end system, because the Business Data Catalog takes care of authentication, authorization, and other security requirements.

Scalar

A Scalar is a method that returns a single value that you can invoke in the back-end LOB application. For example, you can use a Scalar method to get the total sales made to date from the back-end application.

Entities have zero or more Scalar methods.

Example

<MethodInstances>
            <MethodInstance Type="SpecificFinder" ReturnParameterName="LineItem" ReturnTypeDescriptorName="LineItem" ReturnTypeDescriptorLevel="0" Name="FindLineItemInstance" />
</MethodInstances>

Schema

See Also

Tasks

AdventureWorks SQL Server 2000 Sample
How to: Get Started with Using the Runtime Object Model
How to: Get Started with Using the Administration Object Model

Concepts

FAQ: Business Data Catalog
Business Data Catalog: Glossary
Business Data Catalog Security Trimmer
AccessChecker Samples