2.1.3.31 MethodInstance

Target namespace: http://schemas.microsoft.com/windows/2007/BusinessDataCatalog

Referenced by: Association, MethodInstances

A complex type that specifies a MethodInstance.

Child Elements:

LocalizedDisplayNames: A LocalizedDisplayNames element (section 2.1.3.28) that specifies the localized names of the Model.

Properties: A Properties element (section 2.1.3.39) that specifies the Properties of the Model.

AccessControlList: An AccessControlList element (section 2.1.3.2) that specifies the access control list (ACL) of the Model.

Attributes:

Type: A MethodInstanceType attribute (section 2.1.4.8) that specifies the type of the MethodInstance.

Default: An xs:boolean attribute that specifies whether the MethodInstance is the default among all MethodInstances sharing its type within the containing Entity. This attribute MUST be set to one of the values listed in the following table.

Value	Description
False	The MethodInstance is not the default among all MethodInstances sharing its type within the containing Entity.
True	The MethodInstance is the default among all MethodInstances sharing its type within the containing Entity.

ReturnParameterName: A NameString attribute (section 2.1.4.9) that specifies the name of the Parameter that contains the ReturnTypeDescriptor of the MethodInstance. The Direction attribute of the Parameter MUST have a value of either "Out", "InOut" or "Return".

This attribute MUST be specified for all types of MethodInstances except GenericInvoker,  Deleter, and Updater.

ReturnTypeDescriptorName: A NameString attribute that specifies the name of the ReturnTypeDescriptor of the MethodInstance. The Parameter specified by the ReturnParameterName attribute MUST contain the ReturnTypeDescriptor. This attribute MUST be ignored when ReturnTypeDescriptorPath attribute is specified. This attribute SHOULD NOT<31> be used.

When this attribute is missing, and the ReturnTypeDescriptorPath attribute is not specified, the application utilizing the structure MUST assume the name of the ReturnTypeDescriptor to be the name of the root TypeDescriptor of the Parameter specified by the ReturnParameterName attribute.

ReturnTypeDescriptorLevel: A ReturnTypeDescriptorLevel attribute (section 2.1.4.13) that specifies the depth from the root of the ReturnTypeDescriptor of the MethodInstance, in the tree of nested TypeDescriptors where the root level equals 0. This attribute MUST be ignored. This attribute SHOULD NOT<32> be used.

ReturnTypeDescriptorPath:  An xs:string attribute that specifies the path<33> to the return value of the MethodInstance. The value of this attribute MUST be in the following format as expressed in ABNF as specified in [RFC5234]:

 Path = StartField *(FieldAccess / Indexer)
 PathToken = StartField / FieldAccess / Indexer
 StartField = Field
 FieldAccess = %x2E Field
 Indexer = %x5B Index %x5D
 Index = 1*DIGIT
 Field = %x01-2D / %x2F-5A / %x5E-FF / EscapedDot / EscapedBracket / EscapedSlash
 EscapedDot = %x5C %x2E
 EscapedBracket = %x5C %x5B
 EscapedSlash = %x5C %x5C

Field rule specifies a TypeDescriptor name when the EscapedDot, EscapedBracket and EscapedSlash rules are replaced with the following:

 EscapedDot = %x2E
 EscapedBracket = %x5B
 EscapedSlash = %x5C

The StartField rule specifies the TypeDescriptor that has the name equal to the name specified by Field rule.

The FieldAccess rule specifies the TypeDescriptor that has the name equal to the name specified by Field rule, which is contained by the given TypeDescriptor. The given TypeDescriptor MUST have IsCollection attribute set to false.

The Indexer rule specifies the only TypeDescriptor contained by the given TypeDescriptor. The given TypeDescriptor MUST have IsCollection attribute set to true.

The Index rule specifies the zero based integer index of a data structure in a collection of data structures.

Given a set of data structures and their corresponding TypeDescriptors, the path string MUST be evaluated to return the specified data structure as follows:

 INIT CurrentTypeDescriptor 
 INIT CurrentDataStructure
 FOR each PathToken in Path from left to right
 IF PathToken is StartField THEN 
 SET CurrentTypeDescriptor to the TypeDescriptor specified by StartField from given TypeDescriptors
 SET CurrentDataStructure to the data structure corresponding to CurrentTypeDescriptor from given data structures
 ELSE IF PathToken is FieldAccess THEN
 SET CurrentTypeDescriptor to the TypeDescriptor specified by FieldAccess given CurrentTypeDescriptor
 SET CurrentDataStructure to the data structure represented by the LobName attribute of CurrentTypeDescriptor from CurrentDataStructure
 ELSE IF PathToken is Indexer THEN
 SET CurrentTypeDescriptor to the TypeDescriptor specified by Indexer given CurrentTypeDescriptor
 SET CurrentDataStructure to the data structure at index specified by Index within CurrentDataStructure
 END IF
 END LOOP
 RETURN CurrentDataStructure

For a specified Path all the specified TypeDescriptors MUST be available.

For example:

Given following data structure (represented in "<property name> : <property value>" pairing)

Customer

Name : "Blake"

Surname : "Donley"

Addresses : Collection of Address data structures

Address

Street : "1 Road"

Zip : "00001"

Address

Street : "2 Road"

Zip : "00002"

Address

Street : 3 Road"

Zip : "00003"

And the corresponding TypeDescriptor structure (represented in "<name>, <lob name>, <Iscollection>" attribute triplets)":

Customer, Customer, false

Name, Name, false

Last Name, Surname, false

Addresses, Addresses, true

Address, Address, false

Street, Street, false

ZipCode, Zip, false

The path "Customer.Addresses[1].ZipCode" specifies the data structure name "Zip" with value "00002"; The path "Customer.LastName" specifies the data structure with name "Surname" with value "Donley"; And the path "Customer.Addresses" specifies the data structure with name "Addresses" that contains a collection of Address data structures.

When this attribute is missing, and the ReturnTypeDescriptorName attribute is not specified, the application utilizing the structure MUST assume the name of the ReturnTypeDescriptor to be the name of the root TypeDescriptor of the Parameter specified by the ReturnParameterName attribute.

Name: A NameString attribute (section 2.1.4.9) that specifies the name of the Model.

DefaultDisplayName: A NameString attribute that specifies the default display name of the Model.

IsCached: An xs:boolean attribute that specifies whether the Model is used frequently. This MAY<34> be used as a recommendation as to whether to cache the Model. This attribute MUST be set to one of the values listed in the following table.

Value	Description
False	The Model is infrequently used.
True	The Model is frequently used.

The following W3C XML Schema ([XMLSCHEMA1/2] section 2.1) fragment specifies the contents of this complex type.

 <xs:complexType name="MethodInstance">
   <xs:complexContent>
     <xs:extension base="bdc:IndividuallySecurableMetadataObject">
       <xs:attribute name="Type" type="bdc:MethodInstanceType" use="required"/>
       <xs:attribute name="Default" type="xs:boolean" use="optional" default="false"/>
       <xs:attribute name="ReturnParameterName" type="bdc:NameString" use="optional"/>
       <xs:attribute name="ReturnTypeDescriptorName" type="bdc:NameString" use="optional"/>
       <xs:attribute name="ReturnTypeDescriptorLevel" type="bdc:ReturnTypeDescriptorLevel" use="optional"/>
       <xs:attribute name="ReturnTypeDescriptorPath" type="xs:string" use="optional"/>
     </xs:extension>
   </xs:complexContent>
 </xs:complexType>

See section 5.1 for the full W3C XML Schema ([XMLSCHEMA1/2] section 2.1).