Creación y personalización de los servicios REST con la infraestructura de correlación de BOD

HCL Commerce proporciona una JET (Java Emitter Template) denominada patrón de recursos RESTful de JET como parte de la infraestructura de correlación de BOD. El patrón de recursos RESTful de JET genera una clase Java anotada JAX-RS que proporciona servicio REST para un recurso específico. Para generar estos archivos, debe crear un archivo de entrada de patrón que contenga especificaciones que son necesarias para implementar el servicio REST utilizando un nombre BOD.

Requisitos previos para utilizar el patrón de recursos RESTful de JET

El patrón de recursos RESTful de JET funciona en Eclipse Modeling Framework (EMF) y utiliza las plantillas JET (Java Emitter Templates) para generar el código fuente. Antes de empezar, asegúrese de que EMF con JET esté instalado en el entorno de desarrollo.

Asegúrese de instalar el paquete JET en el entorno de developer de HCL Commerce. Para obtener más información, consulte Instalar el paquete JET (Java Emitter Template).

Asegúrese de que están instalados los ID de plugin siguientes:

org.eclipse.emf.codegen
com.ibm.commerce.toolkit.internal.pattern.rest

Formato del archivo de entrada de patrones

El archivo de entrada de patrones proporciona la información necesaria para el patrón de recursos de JET RESTful en el siguiente formato:


<rest 
   componentName="component_name" 
   packageNamePrefix="package_name_prefix">
  <noun 
        name="noun_name" 
        pluralNounName="plural_noun_name" 
        resourceName="resource_name"
      actionExpression="action_expression" 
        actionExpressionSuffix="action_expression_suffix" 
        defaultAccessProfile="default_access_profile" 
        defaultExpression="default_get_xpath_expression">
       <findBy 
         expression="get_xpath_expression" 
         name="findby_name"
         accessProfile="get_access_profile"/>
       <delete 
         key="key_to_delete" 
         method="delete_method"/>
       <create 
         for="create_for" 
         method="create_method"/>
   <update 
         for="update_for" 
         method="update_method"/>
  </noun>
</rest>

Nota: El resourceName no tiene que coincidir con el nombre de nombre en un archivo XML de entrada de patrón. Asegúrese de que el resourceName que especifique no coincida con ninguno de los recursos REST predeterminados.

La siguiente tabla describe las variables en el archivo XML de entrada de patrón:


Variable de archivo de entrada	Obligatorio	Descripción:
`component_name`	Sí	El nombre del componente que contiene el servicio web a partir del cual desea crear un servicio REST. Si está utilizando un servicio existente de HCL Commerce, obtenga el nombre de componente revisando la lista de este tema: HCL Commerce Servicios web Algunos ejemplos de nombres de componentes son: Catálogo Marketing Orden Si está creando un servicio REST a partir de un servicio web de HCL Commerce, utilice el nombre del componente que contenga el servicio web personalizado.
`package_name_prefix`	Sí	El prefijo del paquete que contendrá la salida de la clase Java de este patrón. En el caso de un servicio REST procedente de un nombre de HCL Commerce, utilice `com.ibm.commerce`. Para un servicio REST a partir de un nombre personalizado, utilice `com.your_company_name.commerce`, por ejemplo, `com.mycompany.commerce`
`noun_name`	Sí	El nombre del nombre que desea utilizar para implementar el servicio REST. Para ver los nombres disponibles para los componentes de HCL Commerce, consulte HCL CommerceServicios web.
`plural_noun_name`	Sí	La forma plural del nombre que desea utilizar para implementar el servicio REST. El convenio es para especificar el mismo valor singular en un URL de RESTful. Por ejemplo, si un nombre es Persona, ambos valores, `noun_name` y `plural_noun_name`, deben establecerse en Persona.
`resource_name`	No	El nombre del recurso REST que desea especificar para un servicio REST.
`action_expression`	No	La expresión de acción del nombre o su subnombre. Por ejemplo: `AddressBook/Contact`.
`action_expression_suffix`	No	El sufijo de la expresión de acción del nombre o su subnombre. Por ejemplo: `[1]`.
`default_access_profile`	Sí	El nombre del perfil de acceso de escaparate predeterminado que se utilizará para la petición de servicio de HCL Commerce. El perfil de acceso define los datos que incluir en la respuesta. Los perfiles de acceso se definen para cada nombre en HCL CommerceServicios web. Generalmente, los perfiles de acceso del escaparte comienzan con `IBM_Store` en lugar de `IBM_Admin`.
`default_get_xpath_expression`	No	La expresión XPath para el servicio GET que obtiene todas las instancias de un nombre, en lugar de devolver una instancia específica del nombre por su identificador. Incluya este parámetro en el archivo de entrada de patrones solo si necesita que el recurso de JAX-RS obtenga todas las instancias de un nombre. Por ejemplo, el nombre Catalog tiene una expresión XPath GET que obtiene todos los catálogos de ventas de la tienda. En este caso, el atributo en el archivo de entrada de patrones es: `defaultExpression="/Catalog[@primary='false']"` Si el URL de RESTful no incluye un identificador, el recurso de JAX-RS utiliza la `default_get_xpath_expression`.
`get_xpath_expression`	Sí 1	La expresión XPath para el servicio GET que obtiene un nombre al utilizar el identificador interno o externo que haya especificado en el URL en el procedimiento anterior. Ejemplo de una expresión XPath que utiliza un servicio interno Get Catalog mediante identificador: `/Catalog[CatalogIdentifier[(UniqueID=)]]` Esta expresión XPath obtiene un catálogo al utilizar su ID exclusivo y devuelve el catálogo que coincide con el ID. Importante: Cuando incluya la expresión XPath en el archivo de entrada de patrones, especifique los siguientes caracteres para el valor UniqueID numérico, independientemente de lo que está en la expresión XPath documentada: `{0}` La expresión XPath del ejemplo anterior debe parecerse a la siguiente serie en el archivo de entrada de patrones: `/Catalog[CatalogIdentifier[(UniqueID={0})]]` Nota: HCL Commerce no proporciona un servicio web RESTful para el nombre Catalog, pero puede crear uno utilizando los procedimientos de esta sección. Ejemplo una expresión XPath que utiliza un servicio externo Get MarketingSpotData mediante identificador: `/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=)]]]` Esta expresión XPath obtiene los datos de la zona de e-Marketing utilizando su identificador externo (en este caso, su nombre) y devuelve los datos para mostrarlos a un cliente. Importante: Cuando incluya la expresión XPath en el archivo de entrada de patrones, si el valor del identificador es una serie, especifique los siguientes caracteres para el valor de serie, independientemente de lo que está en la expresión XPath documentada: `\"{0}\"` La expresión XPath del ejemplo anterior debe parecerse a la siguiente serie en el archivo de entrada de patrones: `/MarketingSpotData[MarketingSpotIdentifier[ExternalIdentifier[(Name=\"{0}\")]]]`
`findby_name`	Sí 1	El sufijo del método llamado cuando el URL contiene un identificador. El patrón crea un método al utilizar este sufijo para el nombre. En la clase Java generada, el nombre de método completo será `findByfindby_name`. El valor de `findby_name` debe coincidir con el identificador especificado para expresión XPath del servicio Get. Por ejemplo, para la expresión XPath Get Catalog en la fila anterior, un valor de `findby_name` apropiado será `Id`.
`get_access_profile`	Sí 1	El nombre del perfil de acceso que se utilizará para la petición de servicio get de HCL Commerce. El perfil de acceso define los datos que incluir en la respuesta.
`key_to_delete`	Sí 1	El identificador o clave exclusiva para eliminar un recurso en un servicio de HCL Commerce.
`delete_method`	Sí 1	El método Delete de una clase de fachada de cliente de servicio de HCL Commerce, que toma `Map` como parámetro. Por ejemplo: `MemberFacadeClient.deleteAddressForPerson(java.util.Map)`.
`create_for`	Sí 1	El recurso que se va a crear utilizando un servicio de HCL Commerce.
`create_method`	Sí 1	El método Create de una clase de fachada de cliente de servicio de HCL Commerce, que toma `Map` como parámetro. Por ejemplo: `MemberFacadeClient.addAddressForPerson(java.util.Map)`.
`update_for`	Sí 1	El recurso que se va a actualizar utilizando un servicio de HCL Commerce.
`update_method`	Sí 1	El método Update de una clase de fachada de cliente de servicio de HCL Commerce, que toma `Map` como parámetro. Por ejemplo: `MemberFacadeClient.updateAddressForPerson(java.util.Map)`.

Nota: 1 Estas variables son necesarias si se definen las acciones respectivas (findBy, create, update y delete). Se necesita, como mínimo, una definición de acción para el nombre. Se da soporte a varios nombres y acciones en el archivo de patrones XML de entrada. El archivo de patrones XML de entrada debe contener valores exclusivos para el nombre de nombre, clave, for y los nombres de método.

Archivo de entrada de patrones de ejemplo

Este archivo de entrada de ejemplo genera las clases Java y los archivos de propiedades necesarios para poder trabajar con el servicio de miembro para crear, actualizar, recuperar y eliminar los recursos disponibles:


<rest 
   componentName="Member" 
   internal="false" 
   packageNamePrefix="com.ibm.commerce">
  <noun 
       name="Person" 
       pluralNounName="Person" 
       resourceName="Person"
     actionExpression="AddressBook/Contact" 
       actionExpressionSuffix="" 
       defaultAccessProfile="IBM_Store_Details" 
       defaultExpression="{self=true}/Person">
    <findBy 
      expression="/Person[PersonIdentifier[(UniqueID={0})]]" 
      name="UniqueID" 
      accessProfile="IBM_Store_Details"/>
    <findBy 
      expression="/Person[Credential[LogonID={0}]] " 
      name="LogonID" 
      accessProfile="IBM_Store_Details"/>
    <delete 
      key="ContextAttribute" 
      method="deleteContextAttributeForPerson"/>
    <create 
      for="Person" 
      method="registerPerson"/>
    <update 
      for="Person" 
      method="updatePerson"/>
  </noun>
</rest>

Generación del código fuente

Efectúe los pasos siguientes para generar el código fuente para los servicios REST:

Cree un archivo XML debajo del directorio project/location de personalización (WebSphereCommerceServerExtensionsLogic) y copie en él el archivo de entrada de ejemplo. Realice los cambios necesarios en el archivo, de acuerdo con la tabla de especificaciones de entrada de la sección Formato del archivo de entrada de patrones.
Guarde los cambios efectuados en el archivo. A continuación, Haga clic en el botón derecho del ratón en el archivo y seleccioneEjecutar como > Ejecutar configuraciones.
Seleccione Transformación JET y, a continuación, Haga clic en el botón derecho del ratón y seleccione Nuevo. Se crea una configuración nueva.
El archivo XML generado aparece en la sección Entrada de transformación. Seleccione el ID de transformación como com.ibm.commerce.toolkit.internal.pattern.rest:
Seleccione Aplicar > Ejecutar para comenzar la transformación.
Después de ejecutar la transformación satisfactoriamente, se generarán los archivos de salida debajo del proyecto WebSphereCommerceServerExtensionsLogic.
Compruebe si hay errores de compilación en las clases Java, que pueden producirse debido a que falte un archivo JAR en la vía de acceso de clases, y rectifíquelos.

Ubicación del archivo de salida de patrones

El patrón genera los archivos en los directorios siguientes:

Clases de manejador de recursos: src\package_name.rest.extension.resource_name.handler
Clases de ayudante de recursos: src\package_name.rest.extension.bod.helpers
Archivos de correlación XML de BOD: WebContent\WEB-INF\config\bodMapping-ext
Archivo XML de la biblioteca de cliente de servicio: WebContent\WEB-INF\config\bodMapping-ext
Archivo de propiedades de recurso: WebContent\WEB-INF\config
Archivo XML de configuración de recurso: WebContent\WEB-INF\config\com.ibm.commerce.rest-ext

Consumo del código generado

Efectúe los pasos siguientes para consumir el código generado para la personalización:

Copie el archivo rest-resource_name-clientobjects.xml en la ubicación similar que aparece debajo del proyecto REST en el espacio de trabajo. Añada los valores XPath adicionales a las correlaciones de atributo para el nombre que haya seleccionado en el archivo XML de entrada. El valor XPath se llena en los datos de respuesta relativos a los atributos correlacionados.
Copie el archivo resources-ext.properties en la ubicación similar del proyecto Rest, o fusione las entradas de los archivos de la clase de manejador de recursos añadida recientemente.
Copie el archivo wc-rest-resourceconfig.xml en la ubicación similar en el proyecto REST. Cree la carpeta WEB-INF\config\com.ibm.commerce.rest-ext si todavía no existe.
Copie el archivo wc-service-client-library.xml en la ubicación similar del proyecto Rest, o fusione las entradas de los archivos de la clase de manejador de recursos añadida recientemente.

Probar la personalización

Reinicie el servidor de pruebas e invocar el URI de la clase de manejador de recursos recién añadida.

El URI debería ser similar a la dirección siguiente:

Para obtener una petición Get (valor Person del contexto):

http://host_name/wcs/resources/store/10101/person

Para obtener una petición Get (valor Person con el ID de inicio de sesión):

http://host_name/wcs/resources/store/10101/person/byLogonId/personID