Notación XPath ampliada de HCL Commerce

Cuando se procesan solicitudes get para nombres de HCL Commerce, HCL Commerce utiliza la notación XPath ampliada como lenguaje de consulta para identificar qué nombres se deben devolver. XPath es un lenguaje estándar de la industria para direccionar partes de un documento XML, y la notación XPath ampliada de HCL Commerce utiliza extensiones de este estándar.

Se utiliza la notación XPath debido a que los nombres se definen en un esquema XML y se pueden considerar como documentos XML. HCL Commerce convierte estos nombres en una clase de Java que se llama Service Data Objects (SDO). Las propiedades de SDO se pueden representar como atributos en casos simples como por ejemplo, Series o elementos cuando las propiedades de SDO hacen referencia a otro objeto SDO. Estos objetos SDO y esquemas XML forman el modelo lógico de HCL Commerce.

Notación XPath de correlación

Cuando se utilizan expresiones XPath para solicitar nombres, HCL Commerce no utiliza las API XPath de Java. HCL Commerce correlaciona la expresión XPath en la petición GET con una consulta SQL que está definida en un archivo de plantilla de consulta (archivo .tpl). La consulta SQL contiene variables que HCL Commerce sustituye en tiempo de ejecución. Para correlacionar una expresión XPath con una consulta SQL, HCL Commerce normaliza la expresión XPath y asocia la expresión con una clave XPath. Para normalizar la expresión HCL Commerce elimina los valores de datos reales en XPath. Puede utilizar el generador de claves XPath para normalizar una expresión XPath específica. El programa de utilidad de línea de mandatos generador de claves XPath toma, como entrada, una expresión XPath, y genera una clave XPath. Esta clave se utiliza para localizar la consulta SQL en el archivo de plantillas de consulta.

El siguiente fragmento de código es un ejemplo de una expresión XPath que no está normalizada:
/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='ABC123')]]]
Para normalizar esta consulta, HCL Commerce elimina el valor de PartNumber. El siguiente código muestra el formato normalizado de esta consulta:
/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber=)]]]
HCL Commerce crea una variable PartNumber que se puede utilizar en la sentencia SQL que está asociada con este XPath. La sentencia SQL está definida en un archivo de plantillas de consulta. En la siguiente sentencia SQL se muestra el uso de la variable PartNumber. Esta variable, ?PartNumber? se sustituye durante la ejecución por valores de datos reales.
SELECT
CATENTRY_ID_1
FROM
(
SELECT
CATENTRY.CATENTRY_ID CATENTRY_ID_1
FROM
CATENTRY
WHERE
CATENTRY.PARTNUMBER IN (?PartNumber?) AND
CATENTRY.MARKFORDELETE = 0 AndPSAgreements
) T1
WHERE EXISTS
(
SELECT
1
FROM
STORECENT
WHERE
CATENTRY_ID_1 = STORECENT.CATENTRY_ID AND
STORECENT.STOREENT_ID IN ( $STOREPATH:catalog$ )
)

Para obtener más información sobre el generador de claves XPath y la normalización de expresiones XPath, consulte Generar la clave XPath mediante el programa de utilidad wcs_xpathkey

Para obtener más información sobre cómo las expresiones XPath se correlacionan con la plantilla de consulta SQL, consulte el archivo de plantillas de consulta.

Puede crear sus propios métodos para consultar nombres definiendo sus propias correlaciones XML en el archivo de plantillas de consulta. Para obtener más información sobre cómo crear sus propias consultas, consulte Creación de una consulta.

Estructura de notación de XPath

Cuando utilice el lenguaje XPath, asegúrese de que el XPath coincide con el esquema lógico del nombre de respuesta. Por ejemplo, si se especifica el siguiente XML de nombre:
<Catalog>
    <CatalogGroup>
      <Name>MyCatalogGroupName</Name>
    </CatalogGroup>
</Catalog>
El siguiente ejemplo de expresión XPath muestra cómo obtener nombres de CatalogGroup basándose en el atributo de nombre:
/CatalogGroup[Name='MyCatalogGroupName']
La expresión XPath coincide con la estructura del esquema lógico. La expresión está formada por los componentes siguientes: 
{control parameters}/root node[predicate expressions]
  • Los parámetros de control especifican los controles de acceso o identifican que las condiciones de consulta no se pueden capturar con el modelo lógico. Este parámetro identifica cuántos datos se han de devolver para los objetos consultados. Por ejemplo, un parámetro de control {_wcf.ap=IBM_Admin_All} es un perfil de acceso. Los perfiles de acceso se correlacionan con consultas en el archivo de plantillas de consulta e indican que se ha de devolver una vista administrativa de la información de objeto. Los parámetros de control que no se pueden capturar con el modelo lógico pueden incluir peticiones para devolver información sobre el usuario actual o para un idioma específico. Por ejemplo, el parámetro de control {self=true} indica que la información del objeto se ha de recuperar basándose en el usuario actual. Esta información no se puede capturar con el modelo lógico y se basa en el ID de usuario actual almacenado en el contexto del mandato.
  • El nodo raíz suele ser el nombre del nombre que se ha de devolver. Es el elemento raíz del documento XML del nombre. En el ejemplo anterior, el nodo raíz es CatalogGroup, lo que se indica mediante /CatalogGroup.
  • Las expresiones de predicado identifican los parámetros para la información que la consulta va a recuperar. Cada parámetro se utiliza en una sentencia condicional que debe cumplirse para que se devuelvan los nombres. La expresión de predicado se define con corchetes [expresión de predicado]. En el ejemplo anterior, la consulta va a devolver nombres CatalogGroup donde CatalogGroup tiene el nombre 'MyCatalogGroupName'.
Para obtener más información sobre los elementos XPath y los parámetros de control, consulte Parámetros SQL.

Creación de expresiones XPath

Al crear sus propias expresiones XPath, puede crear expresiones simples y complejas. Normalmente, las expresiones XPath simples se definen y correlacionan explícitamente con consultas SQL en los archivos de plantilla de consulta. HCL Commerce, sin embargo, proporciona otra forma más dinámica para consultar objetos. Puede utilizar la función search() para crear una expresión XPath más compleja para consultar objetos. La función search() se puede utilizar para reducir el número de consultas que un desarrollador tiene que crear. La función search() se puede colocar en una expresión de predicado que esté dentro de una expresión XPath. Cuando se utiliza esta expresión de búsqueda, no es necesario definir cada consulta en el archivo de plantilla de consulta. HCL Commercegenera automáticamente la consulta en tiempo de ejecución basándose en el contenido de la expresión de búsqueda. Para obtener más información sobre la creación de expresiones XPath con la función search(), consulte Soporte de búsqueda paramétrica.

Cuando cree alguna expresión XPath, utilice las siguientes reglas de sintaxis y sugerencias como ayuda para especificar parámetros de control, nodos raíz y expresiones de predicado:
  • Parámetros de control: todos los parámetros de control están definidos dentro de un mismo conjunto de corchetes { }
  • Parámetros de control: asegúrese de incluir los prefijos necesarios cuando defina parámetros. Todos los perfiles de acceso se prefijan con _wcf.ap=. Por ejemplo, para definir el perfil de acceso IBM_Admin_All utilice {_wcf.ap=IBM_Admin_All}
  • Parámetros de control - para añadir más parámetros, utilice un punto y coma. Por ejemplo, {self=true; _wcf.ap=IBM_Admin_All; _wcf.dataLanguageIds='-1'}
  • Nodo raíz - el nodo raíz debe identificarse mediante una barra inclinada '/' seguida de la vía de acceso relativa.
  • Expresiones de predicado - todas las expresiones de predicado se definen entre conjuntos de corchetes [ ].
  • Expresiones de predicado - puede anidar expresiones para definir consultas que han de devolver información basada en varias condiciones. Por ejemplo, la expresión [OrganizationIdentifier[(DistinguishedName='DN01')]] define que la consulta va a devolver nombres que tienen un OrganizationIdentifier con un DistinguishedName de 'DN01'
  • Expresiones de predicado - la función 'search' se utiliza con expresiones XPath. Identifique la función de búsqueda, search(), dentro del predicado e incluya los parámetros de búsqueda dentro del conjunto de paréntesis ( ). Por ejemplo, la expresión de nodo raíz y predicado /CatalogGroup[search(CatalogGroupIdentifier/ExternalIdentifier/GroupIdentifier='T')] identifica una expresión de búsqueda. Esta expresión identifica que se ha de devolver información de CatalogGroup cuando GroupIdentifier es 'T'.
  • Parámetros de control y expresiones de predicado - puede utilizar operadores estándar como, por ejemplo, '<' '<=' '>' '>=' '=' '!=' '&' '|'
  • Parámetros de control y expresiones de predicado - A los elementos que se repiten 0 o más veces se les añade como sufijo un asterisco.
  • Parámetros de control y expresiones de predicado - A los elementos que se repiten 1 o más veces se les añade como sufijo un signo '+'.
  • Parámetros de control y expresiones de predicado - Cuando los elementos tienen que agruparse, póngalos entre paréntesis ().

Ejemplos de expresiones XPath

Como ayuda para crear expresiones XPath para consultar modelos lógicos, las siguientes expresiones de ejemplo validan la sintaxis de expresiones XPath simples:

{_wcf.ap=IBM_Admin_All}/Organization[OrganizationIdentifier[(DistinguishedName='DN01')]]
En el ejemplo anterior, la expresión XPath define una consulta para devolver información sobre la organización basada en el nombre distinguido de la organización. Esta expresión se compone de:
  • El parámetro de control {_wcf.ap=IBM_Admin_All}, que es un perfil de acceso que identifica que se debe devolver una vista administrativa de toda la información para los objetos.
  • El nodo raíz /Organization, que identifica que la expresión XPath está consultando información en el nodo Organization del documento XML.
  • La expresión de predicado [OrganizationIdentifier[(DistinguishedName='DN01')]]. Este predicado identifica que la consulta solo va a devolver la información para organizaciones con un OrganizationIdentifier que tenga un DistinguishedName de 'DN01'.
{_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='DU0101' 
             or PartNumber='DU0102')]]]
En el ejemplo anterior, la expresión define una consulta para devolver información de resumen sobre una entrada de catálogo teniendo en cuenta el número de pieza. Esta expresión XPath se compone de:
  • Parámetros de control {_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}. Estos parámetros identifican que la consulta va a devolver una vista administrativa de la información de resumen para los objetos en el idioma de tienda especificado.
  • El nodo raíz /CatalogEntry identifica que la expresión XPath devuelve nombres CatalogEntry.
  • La expresión de predicado [CatalogEntryIdentifier[ExternalIdentifier[(PartNumber='DU0101' or PartNumber='DU0102')]]]. Este predicado identifica que la consulta solo va a devolver entradas de catálogo en las que CatalogEntryIdentifier contiene un ExternalIdentifier que es un PartNumber con un valor de DU0101 o DU0102.

Los ejemplos de código siguientes ofrecen ejemplos adicionales de expresiones XPath válidas:
{_wcf.ap=IBM_Admin_Summary;_wcf.dataLanguageIds='-1'}/CatalogEntry[ParentCatalogGroupIdentifier[(UniqueID='10128')]]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogGroup[ParentCatalogGroupIdentifier[(UniqueID='10125')]

{_wcf.ap=IBM_Admin_CatalogEntryMerchandisingAssociations;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[(UniqueID='10541')]]

{_wcf.ap=IBM_Admin_CatalogEntryAttachmentReference;_wcf.dataLanguageIds='-1'}/CatalogEntry[CatalogEntryIdentifier[(UniqueID='10541')]]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogGroup[@topCatalogGroup='true']

Ejemplos de expresiones de consulta con funciones de búsqueda

Como ayuda para crear expresiones XPath que utilizan funciones de búsqueda para consultar los modelos lógicos, las siguientes expresiones de ejemplo muestran la sintaxis válida de las expresiones XPath:

{_wcf.ap=IBM_Admin_CatalogGroupAllParentsDetails;_wcf.dataLanguageIds='-1'}
    /CatalogGroup[search(CatalogGroupIdentifier/ExternalIdentifier/GroupIdentifier='T' or Description/Name='T')]
En este ejemplo, la expresión XPath define una consulta que devuelve información de CatalogGroup basada en los resultados de la búsqueda. La expresión identifica que HCL Commerce debe devolver información para grupos de catálogos con un GroupIdentifier o un Description/Name con un valor de 'T'. La función de búsqueda especifica que se busque en GroupIdentifier el nodo ExternalIdentifier para el CatalogGroupIdentifier de CatalogGroup .
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') 
   and search(CatalogEntryIdentifier/ExternalIdentifier/PartNumber='T' or Description/Name='T')]
En este ejemplo, la expresión incluye una función de búsqueda con una expresión de búsqueda simple y una expresión de búsqueda de comodín. La búsqueda de comodín especifica consultar cualquier catalogEntryTypeCode que esté incluido en el nodo CatalogEntry que tenga un valor de 'PackageBean' o 'DynamicKitBean'. Esta búsqueda de comodín especifica que hay que consultar todos los nodos dentro del nodo raíz CatalogEntry, independientemente de la vía de acceso relativa de la ubicación catalogEntryTypeCode. Esta expresión de búsqueda simple funciona tal como se mostró en el ejemplo de función de búsqueda anterior. Esta expresión de búsqueda se combina con la expresión de búsqueda de comodín para especificar que solo ha de devolverse información que coincida con ambas expresiones de búsqueda.
El siguiente código proporciona más ejemplos de expresiones XPath válidas con funciones de búsqueda:
{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' 
  or @catalogEntryTypeCode='DynamicKitBean') and search(starts-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') 
  or starts-with(Description/Name, 'T'))]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='ProductBean' 
 or @catalogEntryTypeCode='BundleBean' or @catalogEntryTypeCode='PackageBean' or @catalogEntryTypeCode='DynamicKitBean') 
 and search(starts-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') and Description/Name='C' 
 and starts-with(CatalogEntryAttribute/Attributes/mfPartNumber, 'T') and CatalogEntryAttribute/Attributes/mfName='B') 
 and ParentCatalogGroupIdentifier[ExternalIdentifier[GroupIdentifier='Bottom']]]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='BundleBean') 
  and search(contains(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or contains(Description/Name, 'T'))]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='BundleBean') 
  and search(ends-with(CatalogEntryIdentifier/ExternalIdentifier/PartNumber, 'T') or ends-with(Description/Name, 'T'))]

{_wcf.ap=IBM_Admin_Details;_wcf.dataLanguageIds='-1'}/CatalogEntry[(@catalogEntryTypeCode='PackageBean' 
 or @catalogEntryTypeCode='DynamicKitBean') and search(CatalogEntryIdentifier/ExternalIdentifier/PartNumber='T' 
 or CatalogEntryIdentifier/ExternalIdentifier/PartNumber='B' or Description/Name='T' or Description/Name='B')]