MethodInstance

Un objeto MethodInstance describe cómo usar un método a través de un conjunto específico de valores predeterminados y un tipo de instancia de método, que es una semántica del Catálogo de datos profesionales. Un objeto MethodInstance es una referencia a un método, además de los valores predeterminados para los parámetros. Un objeto MethodInstance se puede ejecutar, pero un objeto Método no. Un único método puede tener varias instancias de método, siendo cada objeto MethodInstance una combinación de la firma del método y un conjunto de valores predeterminados. Puede usar instancias de método para ejecutar el mismo método con valores predeterminados diferentes.

Las instancias de método resultan especialmente útiles para los servicios web complejos. Si un método devuelve varias estructuras complejas o una estructura compleja anidada, los metadatos de MethodInstance pueden especificar cuál de las estructuras o qué parte de la estructura se devolverá al cliente. Para definir completamente un objeto MethodInstance, puede definir, de manera opcional, un elemento TypeDescriptor junto con el return parameter en el XML. A continuación, se muestra un ejemplo.

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

El atributo ReturnTypeDescriptorName es opcional. Si no se especifica, el Catálogo de datos profesionales asume la raíz TypeDescriptor del elemento Return parameter. El atributo ReturnTypeDescriptorLevel también es opcional. Si no se ha especificado ningún descriptor de tipo o hay más de uno con el mismo nombre, se producirá una excepción an . Si hay más de un descriptor de tipo con el mismo nombre en el mismo nivel (lo que es poco frecuente), se asume el primero. Esta flexibilidad es importante, ya que permite reutilizar un objeto WebMethod de varias maneras. Imagine un WebMethod que devuelve colecciones de clientes y que cada cliente contiene una colección de direcciones. Hay tres objetos MethodInstance en el Catálogo de datos profesionales que usan este WebMethod: CustomerFinder, CustomerSpecificFinder y CustomerToAddressAssociation (devuelve las direcciones de un cliente). En el modelo MethodInstance, el autor de metadatos debe definir sólo la parte del Return parameter que sea importante, permitiendo al usuario especificar el TypeDescriptor en Return parameter.

Association es una clase derivada de MethodInstance y el formato de definición de Association también toma, de manera opcional, valores de ReturnTypeDescriptor.

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

Finalmente, el modelo de objetos para MethodInstance también proporciona un descriptor de acceso/propiedad ReturnTypeDescriptor. ReturnParameter forma parte implícitamente de ReturnTypeDescriptor y, puesto que el modelo de objetos funciona con las referencias a objetos, ya no es necesario especificar un modelo ReturnParameter al usar el modelo de objetos.

Algunas instancias de método tienen fines especiales que habilitan clientes genéricos.

Finder y SpecificFinder

Finder es un método especial que devuelve instancias de entidad. SpecificFinder devuelve exactamente una instancia de entidad. Los métodos Finder son métodos estáticos y no toman una clave como parámetro de entrada. Los métodos SpecificFinder son también métodos estáticos pero toman una clave (identificador) de forma explícita.

Las entidades que se pueden alcanzar sólo por asociación no deben tener ningún método Finder. Otras entidades deben tener un método Finder que devuelva varias instancias y un método SpecificFinder que devuelva una instancia única, en función de un identificador determinado.

Por ejemplo, para la entidad Customer, el método Finder podría ser SELECT * FROM Customers y el método SpecificFinder podría ser SELECT * FROM Customers WHERE CustomerID = id.

Si no definen métodos Finder, la entidad no se puede usar en un elemento web del Catálogo de datos profesionales; si no definen métodos SpecificFinder, la entidad no puede realizar acciones en él, no se puede buscar o indizar y no se puede usar en ninguna de las características del Catálogo de datos profesionales, excepto el elemento web de lista relacionada.

Para cumplir los requisitos de un método Finder, el método correspondiente debe tomar parámetros que se puedan filtrar como colecciones de registros de entrada y de devolución, donde cada registro debe contener la clave de la instancia de entidad que representa. Para cumplir los requisitos de un método SpecificFinder, el método correspondiente debe tomar la clave de instancia de entidad como uno de los parámetros de entrada y debe devolver campos, de los cuales uno es la clave.

A continuación se muestra un ejemplo un poco más completo de un método Finder que tiene parámetros que se pueden filtrar.

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

Los métodos Finder y SpecificFinder no pueden devolver los mismos campos. Es posible que haya escenarios en los que un método SpecificFinder devuelva más campos que el método Finder. Sin embargo, ambos deben devolver los identificadores definidos en las entidades.

Un método Finder y un método SpecificFinder deben tener exactamente una instancia de método que se corresponda.

Un método SpecificFinder juega un papel muy importante en la indización y en Enterprise Search. El rastreo del Catálogo de datos profesionales se realiza en dos fases:

• Enumeración de identificadores: obtener todos los identificadores de las instancias de entidades.

• Obtención de detalles: obtener detalles para cada instancia de entidad.

Un IDEnumerator, que se describirá más adelante en este tema, devuelve los identificadores y el método SpecificFinder devuelve los detalles de cada instancia de entidad.

ViewAccessors

Una view es una colección de campos para una entidad. La vista de una entidad contiene los campos devueltos por uno de sus objetos MethodInstance como Finder y SpecificFinder. ViewAccessor es otro método especial que devuelve una vista no predeterminada, es decir, un conjunto diferente de campos desde la aplicación empresarial. Los métodos ViewAccessor son métodos de instancia que toman una clave (identificador) de forma implícita; es decir, no se proporciona la clave. El Catálogo de datos profesionales proporciona la clave automáticamente.

Las entidades tienen cero o más métodos ViewAccessor.

Nota

Enterprise Search sólo rastrea la vista SpecificFinder de la entidad.

Aunque los métodos Finder y SpecificFinder sólo pueden tener una instancia de método, ViewAccessor puede tener una o más instancias de método. Esta flexibilidad resulta útil cuando el mismo método devuelve varias estructuras, cada uno de las cuales forma una vista. En sistemas como SAP, algunas API (por ejemplo, BAPI_CUSTOMER_GETDETAIL2) devuelven al usuario varias colecciones de campos relacionados. La API GetDetails del cliente, por ejemplo, puede devolver una estructura que contiene datos financieros, una estructura que contiene datos de direcciones y así sucesivamente.

Nota

Las características de datos profesionales, como las listas y los elementos web de datos profesionales, admiten vistas de entidad.

IDEnumerator

Un rastreo del Catálogo de datos profesionales tiene dos fases:

• Enumeración de identificadores: obtener todos los identificadores de las instancias de entidades.

• Obtención de detalles: obtener detalles para cada instancia de entidad.

Un método IDEnumerator devuelve la lista de identificadores (claves únicas) para cada entidad que debería poder buscarse y el método SpecificFinder devuelve los detalles para cada instancia de entidad. Esto permite la indización de las entidades cuyos identificadores devuelve el método IDEnumerator.

Nota

Si necesita realizar un rastreo incremental, también debe asegurarse de que uno de los campos de devolución en IdEnumerator para la entidad representa la hora en que la instancia de entidad (o fila en la terminología de la base de datos) se actualizó por última vez en la aplicación de línea de negocio (LOB). A continuación, debe establecer la propiedad __BdcLastModifiedTimestamp de la entidad con el nombre del TypeDescriptor en el valor de devolución del IDEnumerator que representa la fecha de la última modificación.

Las entidades tienen uno o ningún método IDEnumerator. Los métodos IDEnumerator no se limitan a devolver una lista de identificadores. Si devuelven otros campos en el parámetro de devolución, el Catálogo de datos profesionales los omite durante el rastreo.

El filtro LastIdSeen permite realizar la fragmentación de métodos IDEnumerator. Para servicios web y otras aplicaciones back-end de no transmisión por secuencias, use el filtro LastIdSeen en el método IDEnumerator para aumentar el rendimiento de la siguiente manera.

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

AccessChecker

Un método AccessChecker es un método que devuelve los derechos que un usuario tiene en una o más instancias de entidad. Un derecho puede ser un único bit o una colección de bits. Los derechos, una vez determinados, pueden usarse en aplicaciones de datos profesionales a través del método Entity.CheckAccess. Por ejemplo, imagine que un usuario crea un elemento web personalizado en el Catálogo de datos profesionales que muestra acciones de creación, edición y eliminación para EntityInstance. Así pues, al definir AccessChecker, el usuario podría llamar a Entity.CheckAccess y habilitar de manera condicional una o varias de las acciones en función de los derechos que se devuelven. Consulte Ejemplos de AccessChecker para obtener ejemplos de AccessChecker.

Las entidades tienen uno o ningún método AccessChecker por entidad.

GenericInvoker

Un método GenericInvoker es un método que se puede invocar en la aplicación back-end de LOB y que no forma parte de los métodos descritos anteriormente. Por ejemplo, puede usar un método GenericInvoker para ejecutar un método en la aplicación back-end para editar una entidad o actualizar el precio por unidad de la tabla Productos.

Las entidades tienen uno o varios métodos GenericInvoker.

Los métodos GenericInvoker son realmente útiles si se está escribiendo un elemento web personalizado que debe invocar una lógica en un sistema de servidor, ya que el Catálogo de datos profesionales se ocupa de los requisitos de autenticación, autorización y otros requisitos de seguridad.

Nota

Las características de datos profesionales, como las listas y los elementos web de datos profesionales, no usan los métodos GenericInvoker. Sin embargo, el modelo de objetos y el esquema XML admiten este tipo de instancia de método.

Scalar

Un método Scalar es un método que devuelve un valor único que se puede invocar en la aplicación back-end de LOB. Por ejemplo, puede usar un método Scalar para obtener el total de ventas realizadas hasta la fecha desde la aplicación back-end.

Las entidades tienen uno o ningún método Scalar.

Ejemplo

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

Esquema

Secundario	Type	Aparece	Valor predeterminado	Límites/valores aceptados	Descripción
Type	Atributo (bdc:MethodInstanceType)	1..1		Finder SpecificFinder ViewAccessor GenericInvoker IdEnumerator Scalar AccessChecker	Finder: el método devuelve un conjunto de instancias de entidad en función de los criterios de filtro especificados. SpecificFinder: el método devuelve una sola instancia de entidad en función del conjunto de identificadores especificado. ViewAccessor: el método devuelve una nueva vista (conjunto de campos) en función de la instancia de entidad especificada. IdEnumerator: el método devuelve identificadores de instancia de entidad. Se usa en el protocolo de búsqueda de dos fases del Catálogo de datos profesionales. Primero se llama a IdEnumerator del objeto de entidad y, después, se llama a FindSpecific de cada instancia para recuperar los detalles. GenericInvoker: cualquier método
ReturnParameterName	Atributo (String)	1..1			El nombre de Parameter del método que el Catálogo de datos profesionales trata como el parámetro de devolución cuando se ejecuta este objeto MethodInstance.
ReturnTypeDescriptorName	Atributo (String)	0..1			El nombre de TypeDescriptor en el parámetro de devolución que el Catálogo de datos profesionales trata como la estructura de devolución cuando se ejecuta este objeto MethodInstance. El atributo ReturnTypeDescriptorName es opcional. Si no se especifica, el Catálogo de datos profesionales asume el TypeDescriptor raíz de ReturnParameter.
ReturnTypeDescriptorLevel	Atributo (Int32)	0..1			El nivel de ReturnTypeDescriptor en el parámetro de devolución. El atributo ReturnTypeDescriptorLevel también es opcional. Si no se especifica y hay más de un TypeDescriptor con el mismo nombre, se produce una excepción. Si hay más de un TypeDescriptor con el mismo nombre en el mismo nivel (lo que es poco frecuente), se asume el primero.

Vea también

Otros recursos

Ejemplo de SQL Server 2000 de AdventureWorks
Procedimiento para familiarizarse con el uso del modelo de objetos Runtime
Procedimiento para empezar a usar el modelo de objetos Administración
Preguntas más frecuentes sobre el Catálogo de datos profesionales
Catálogo de datos profesionales: glosario
Optimizador de seguridad del Catálogo de datos profesionales
Ejemplos de AccessChecker